Commits

Anonymous committed d57b828

وديعة احتياطية

Comments (0)

Files changed (19)

     +------------------+  macro argument invokations. unfortunetly, the array
     |   ARGUMENT_INT_2 |  argument must be invoked more than once. (that, or
     +------------------+  use statement expressions wich makes this non-c code)
+    |     META_PTR     |  <- axulery ptr for attaching extra data to arrays
+    +------------------+  :
     |   ARGUMENT_PTR_1 |  :
     +------------------+  :
     |   ARGUMENT_PTR_2 |  :
     char *a = p;
     int size = SCTA__EXTERN_SIZE(p)[0];
     int len = SCTA__EXTERN_LEN(p)[0];
-    void *what = a+size*(len+1);
+    void *what = SCTA__EXTERN_STORAGE(p);
     
     int i = 0;
     if (comp) {
     if (i < len) return i;
     else return -1;
 }
+
+bool scta_macro_filter_(void **z, bool (*comp)(void *a, void *b)){
+    char *a = *z;
+    int size = SCTA__EXTERN_SIZE(a)[0];
+    int len = SCTA__EXTERN_LEN(a)[0];
+    
+    int i = 0;
+    if (comp) {
+        for(; i < len; ++i) if (comp(a+(i*size), SCTA__EXTERN_STORAGE(a))) {
+            if (!scta_delete(a, i)) {
+                *z = a;
+                return false;
+            }
+            --len;
+            --i;
+        }
+    }
+    else {
+        for(; i < len; ++i) if (!memcmp(a+(i*size), SCTA__EXTERN_STORAGE(a), size)) {
+            if (!scta_delete(a, i)) {
+                *z = a;
+                return false;
+            }
+            --len;
+            --i;
+        }
+    }
+    *z = a;   
+    return true;
+}
 #define SCTA__EXTERN_PTR2(X) SCTA___PTR2(X, -SCTA_HEAD)
 
 #define SCTA__INTERN_STORAGE(X) (((char *) X)+SCTA__OFFSET_HEADER+(SCTA__INTERN_SIZE(X)[0]*SCTA__INTERN_LEN(X)[0]+SCTA__INTERN_SIZE(X)[0]))
-#define SCTA__EXTERN_STORAGE(X) ((X)+(SCTA__EXTERN_SIZE(X)[0]*SCTA__EXTERN_LEN(X)[0]+SCTA__EXTERN_SIZE(X)[0]))
+#define SCTA__EXTERN_STORAGE(X) (((char *) X)+(SCTA__EXTERN_SIZE(X)[0]*SCTA__EXTERN_LEN(X)[0]+SCTA__EXTERN_SIZE(X)[0]))
 
 
 void* scta_macro_new_(size_t size);
 bool scta_macro_delete_subset_(char **z);
 void* scta_macro_subset_(size_t size, int at, int length, void *p);
 int  scta_macro_find_(void *p, bool (*comp)(void *a, void *b));
-
+bool scta_macro_filter_(void **p, bool (*comp)(void *a, void *b));
 
 /*
             ╭──────────╮
 
 */
 
+#define scta_filter(array, element, function)      (((array)[scta_length(array)+1]=element),\
+                                                     scta_macro_filter_((void **) (&array), (function)))
+/*
+sctdoc:scta_filter:
+NAME
+    scta_filter
+
+SYNOPSIS
+    bool scta_filter(type* array, type target, bool test(void *a, void *b))
+                                                     
+DESCRIPTION    
+    This macro filters out any element in `array' if `test()' returns true 
+    when supplied said element and `target'.
+    
+    if `test' is NULL, elements that match target exactly will be removed.
+    
+RETURN
+    true on success and false on error.
+
+*/
+
 #endif
 
 // defines shorthands
         scta_free(z);
         
     }
+    
+    { // testring filter
+        int *a = scta_new(int);
+        assert(scta_push_array(a, ((int[]){1, 2, 0, 5, 0, 0, 42, 2, 55 ,6}), 10));                
+        assert(scta_filter(a, 0, NULL));
+        assert(!memcmp(a, ((int[]){1, 2, 5, 42, 2, 55 ,6, 0}), sizeof(int)*8)); // terminating zero is tested explicitly in spite of it not being part of the array
+        assert(scta_filter(a, 2, NULL));
+        assert(!memcmp(a, ((int[]){1, 5, 42, 55 ,6, 0}), sizeof(int)*6)); // terminating zero is tested explicitly in spite of it not being part of the array
+        assert(scta_filter(a, 2223, NULL));
+        assert(!memcmp(a, ((int[]){1, 5, 42, 55 ,6, 0}), sizeof(int)*6)); // terminating zero is tested explicitly in spite of it not being part of the array
+        scta_free(a);
+        
+        char **z = scta_new(char *);
+        assert(scta_push(z, "cat"));
+        assert(scta_push(z, "hat"));//
+        assert(scta_push(z, "fat"));//
+        assert(scta_push(z, "cat"));
+        assert(scta_push(z, "rat"));//
+        assert(scta_push(z, "cat"));
+        assert(scta_push(z, "cat"));
+        assert(scta_push(z, "cat"));
+        assert(scta_push(z, "bat"));//
+        assert(scta_filter(z, "cat", string_match));
+        assert(scta_find(z, "cat", string_match) == -1);
+        assert(scta_length(z) == 4);
+        scta_free(z);
+    }
+    
+    
     printf("[ok] %10s %d:%d:%d    %s\n", "scta", 
         scta_config_version[0], scta_config_version[1], 
         scta_config_version[2], __TIMESTAMP__);

modules/s/Makefile

-test:
-	true
-	cp /bin/true test
+test: test.c scts.c scts.h
+	clang -o test -g -Wall -Wextra -pedantic -std=c1x scts.c test.c ../a/scta.c -I ../a
+	echo "TODO generate scts on the fly"
 clean:
-	true
+	rm test

modules/s/parts/codepoint.c

 #ifndef SCTS_PART_CODEPOINT
 #define SCTS_PART_CODEPOINT
 char32_t scts_codepoint(char *c);
-int scts_sequence_length_c(char *c);
-int scts_sequence_length_u(char32_t c);
-char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]);
+/*
+sctdoc:scts_codepoint:
 
-#define scts_sequence_length(primary) (_Generic( (0, primary), \
-    char32_t:scts_sequence_length_u, \
-    const char32_t:scts_sequence_length_u, \
-    char *: scts_sequence_length_c, \
-    const char *: scts_sequence_length_c \
-    )(primary))
-    
-#endif
+NAME
+    scts_codepoint
 
-//LIB
-// change names
-int scts_sequence_length_c(char *character){    
-    // Unicode Standard 6.2: Section 3.9: Page 95
-    uint8_t * restrict c = (uint8_t *) character;
-    register int minlen = 0;
-    
-    if (!c) ERETURN(-1, "Null pointer");
-    
-    // assure that string is not abruptly short and get max max length posible if
-    // short. #security 
-    for (;c[minlen] && minlen < 5; ++minlen);
+SYNOPSIS
+    char32_t scts_codepoint(char *c);
     
-    // direct implementation of the spec.
-    if (c[0] >= 0x0 && c[0] <= 0x7f) {
-        return 1;
-    }
-    else if (c[0] >= 0xc2 && c[0] <=  0xdf && 
-                minlen >= 2 && c[1] >= 0x80 && c[1] <= 0xbf) {
-        return 2;   
-    }
-    else if (c[0] == 0xe0 && minlen >= 3 && 
-                c[1] >= 0xA0 && c[1] <= 0xbf &&
-                c[2] >= 0x80 && c[2] <= 0xbf ) {
-        return 3;   
-    }
-    else if (c[0] >= 0xe1 && c[0] <= 0xec && minlen >= 3 && 
-                c[1] >= 0x80 && c[1] <= 0xbf &&
-                c[2] >= 0x80 && c[2] <= 0xbf ) {
-        return 3;   
-    } 
-    else if (c[0] == 0xed && minlen >= 3 && 
-                c[1] >= 0x80 && c[1] <= 0x9f &&
-                c[2] >= 0x80 && c[2] <= 0xbf ) {
-        return 3;   
-    }
-    else if (c[0] >= 0xee && c[0] <= 0xef && minlen >= 3 && 
-                c[1] >= 0x80 && c[1] <= 0xbf &&
-                c[2] >= 0x80 && c[2] <= 0xbf ) {
-        return 3;   
-    }
-    else if (c[0] == 0xf0 && minlen >= 4 && 
-                c[1] >= 0x90 && c[1] <= 0xbf &&
-                c[2] >= 0x80 && c[2] <= 0xbf &&
-                c[3] >= 0x80 && c[3] <= 0xbf ) {
-        return 4;   
-    }
-    else if (c[0] >= 0xf1 && c[0] <= 0xf3 && minlen >= 4 && 
-                c[1] >= 0x80 && c[1] <= 0xbf &&
-                c[2] >= 0x80 && c[2] <= 0xbf &&
-                c[3] >= 0x80 && c[3] <= 0xbf ) {
-        return 4;   
-    }
-    else if (c[0] == 0xf4 && minlen >= 4 && 
-                c[1] >= 0x80 && c[1] <= 0x8f &&
-                c[2] >= 0x80 && c[2] <= 0xbf &&
-                c[3] >= 0x80 && c[3] <= 0xbf ) {
-        return 4;   
-    }
-    else ERETURN(-1, "ill-formed byte sequence");
-}
+DESCRIPTION
+    This function returns the codepoint of the character sequence pointed to
+    by `c'.
 
-int scts_sequence_length_u(char32_t c){
-    // Unicode Standard 6.2: Section 3.9: Page 95
-    #define else_range_return(start, end, ret) else if (c >= start && c <= end) return ret;
-    if (false) return 0;
-    else_range_return(0,        0x7f,       1)
-    else_range_return(0x80,     0x7ff,      2)
-    else_range_return(0x800,    0xfff,      3)
-    else_range_return(0x1000,   0xcfff,     3)
-    else_range_return(0xd000,   0xd7ff,     3)
-    else_range_return(0xe000,   0xffff,     3)
-    else_range_return(0x10000,  0x3ffff,    4)
-    else_range_return(0x40000,  0xfffff,    4)
-    else_range_return(0x100000, 0x10ffff,   4)
-    else ERETURN(-1, "None-valid codepoint: U+%lu", (unsigned long int) c);
-    #undef range_return
-}
+RETURN
+    This function returns the codepoint on success, and -1 sequince is 
+    ill-formed.
 
+EXAMPLE
+    scts_codepoint("٦") == 0x666;
 
-char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]){
-    // Unicode Standard 6.2: Section 3.9: Page 95
-    int size = scts_sequence_length(c);
-    
-    if (!size) ERETURN(NULL, "^");
-    
-    if (size == 1) {
-        buf[1] = 0;
-        buf[0] = c;
-    }
-    else if (size == 2) {
-        buf[2] = 0;
-        buf[1] = (c & 0x3f) | 0x80;
-        c>>=6;
-        buf[0] = (c & 0x1f) | 0xc0;
-    }
-    else if (size == 3) {
-        buf[3] = 0;
-        buf[2] = (c & 0x3f) | 0x80;
-        c>>=6;
-        buf[1] = (c & 0x3f) | 0x80;
-        c>>=6;
-        buf[0] = (c & 0xf) | 0xe0;
-    }
-    else if (size == 4) {
-        buf[4] = 0;
-        buf[3] = (c & 0x3f) | 0x80;
-        c>>=6;
-        buf[2] = (c & 0x3f) | 0x80;
-        c>>=6;
-        buf[1] = (c & 0x3f) | 0x80;
-        c>>=6;
-        buf[0] = (c & 0x7) | 0xf0;        
-    }
-    // If this occurs, something very wrong is happening in scts_byte_character_size
-    else ERETURN(NULL, "could not map codepoint to well-formed byte sequence"); 
-    
-    return buf;    
-}
+SEE ALSO
+    scts_sequence_codepoint
+    scts_sequence_length
+*/
+
+#endif
 
+//LIB
 char32_t scts_codepoint(char *c){
     // Unicode Standard 6.2: Section 3.9: Page 95
     // (char32_t) -1 error could should be fine because it's not a valid code point
     // validation and string length assertions are preformed in 
     // byte_character_size
     int size = scts_sequence_length(c);
-    if (!size) ERETURN(0, "^");
+    if (size == -1) ERETURN(-1, "^");
     
     if (size == 1) return c[0];
     else if (size == 2) {
 #include <string.h>
 
 int main() {
-    char *ltr;
-    debug_fd = stderr;
-    ltr = ""; assert(scts_sequence_length(ltr) == 1);
-    ltr = "s"; assert(scts_sequence_length(ltr) == 1);
-    ltr = "ﺔ"; assert(scts_sequence_length(ltr) == 3);
-    ltr = "س"; assert(scts_sequence_length(ltr) == 2);
-    ltr = "1"; assert(scts_sequence_length(ltr) == 1);
-    ltr = "句"; assert(scts_sequence_length(ltr) == 3);
-    ltr = "😻"; assert(scts_sequence_length(ltr) == 4);
-    
-    debug_fd = NULL;
-    assert(scts_sequence_length((char *) NULL) == (int) -1);
-    debug_fd = stderr;
-    
-    assert(scts_sequence_length((char32_t) 0x663) == 2);
-    assert(scts_sequence_length((char32_t) 0xa) == 1);
-    assert(scts_sequence_length((char32_t) 0xf906) == 3);
-    assert(scts_sequence_length((char32_t) 0x1F63B) == 4);
-    assert(scts_sequence_length((char32_t) 0) == 1);
-    
-    debug_fd = NULL;
-    assert(scts_sequence_length((char32_t) 0xffffff) == (int) -1);
-    assert(scts_sequence_length("\xE0\x9F\x80") == (int) -1);
-    debug_fd = stderr;
-
     assert(0 == scts_codepoint(""));
     assert(0x636 == scts_codepoint("ض"));
     assert(0xF906 == scts_codepoint("句"));
     assert(0x55 == scts_codepoint("U"));
     assert(0x1F63B == scts_codepoint("😻"));
     
-    
     debug_fd = NULL;
     assert(scts_codepoint(NULL) == (char32_t) -1);
     assert(scts_codepoint("\xE0\x9F\x80") == (char32_t) -1);
     debug_fd = stderr;
-    
-    char buf[5];
-    assert(!strcmp(scts_sequence_codepoint(0, buf), ""));
-    assert(!strcmp(scts_sequence_codepoint(0x666, buf), "٦"));
-    assert(!strcmp(scts_sequence_codepoint(0x23, buf), "#"));
-    assert(!strcmp(scts_sequence_codepoint(0xF906, buf), "句"));
-    assert(!strcmp(scts_sequence_codepoint(0x1F63B, buf), "😻"));
-    
     return 0;
 }
 

modules/s/parts/flow.c

+#include "scts.h"
+
+//HEADER
+#ifndef SCTS_PART_FLOW
+#define SCTS_PART_FLOW
+
+#define SCTS_STOP       (int) 0
+#define SCTS_APPEND     (int) 1
+#define SCTS_INSERT     (int) 2
+#define SCTS_JOIN       (int) 3
+#define SCTS_REPLACE    (int) 4
+#define SCTS_SPLIT      (int) 5
+#define SCTS_SUBSTRING  (int) 6
+#define SCTS_JOIN_LIST  (int) 7
+#define SCTS_NTH        (int) 8
+#define SCTS_COUNT      (int) 9
+
+char32_t* scts_flow_iu(char32_t *primary, ...);
+
+#define scts_flow(primary) (_Generic( (0, primary), \
+    char32_t *:         scts_flow_iu, \
+    char32_t **:        scts_flow_mu, \
+    const char32_t *:   scts_flow_iu, \
+    const char32_t **:  scts_flow_mu, \
+    char *:             scts_flow_ic, \
+    char **:            scts_flow_mc, \
+    const char *:       scts_flow_ic, \
+    const char **:      scts_flow_mc  \
+    )(primary))
+
+/*
+sctdoc:scts_flow:
+
+NAME
+    scts_flow
+
+SYNOPSIS
+    int generic_dummy([char*][char32_t*] primary)
+    
+    int generic_dummy_c(char *primary)
+    int generic_dummy_u(char32_t *primary)
+    
+DESCRIPTION
+    ...
+
+RETURN
+    ...
+
+EXAMPLE
+    ...
+
+SEE ALSO
+    ...
+*/
+
+#endif
+
+//LIB
+#include <stdarg.h>
+char32_t* scts_flow_iu(char32_t *primary, ...){
+    #define type_string 1
+    #define type_list 2
+    int index = 0; // clearer error messages
+
+    #define CHECK_INPUT_IS_STRING  if (last_output_type != type_string) {\
+        EPRINT("incompatible flow: list -> string at argument %d", index);\
+        goto SUPER_ERROR;\
+    }
+    
+    #define CHECK_INPUT_IS_LIST  if (last_output_type != type_list) {\
+        EPRINT("incompatible flow: list -> string at argument %d", index);\
+        goto SUPER_ERROR;\
+    }
+    
+    // input checks
+    if (!primary) primary = (char32_t[]) {0};
+
+    
+    // logic
+    if (!(primary = scts_new(primary))) ERETURN(NULL, "^"); // primary will be
+                                                            // used as the acc
+                                                            // variable
+    int last_output_type = type_string; // last_output_type stores the output type 
+                                     // of the last operation preformed. This is
+                                     // used to make sure that the input of the 
+                                     // next operation is compatible with that 
+                                     // output
+                                                            
+    char32_t **list = NULL;
+    
+    va_list ar;
+    va_start(ar, primary);
+    
+    while (true) {
+        int op = va_arg(ar, int);
+        ++index;
+        
+        switch (op) {
+            case SCTS_STOP:
+                goto SUPER_DONE;
+                break;
+             
+            // str -> str
+            case SCTS_APPEND: {
+                CHECK_INPUT_IS_STRING;
+                char32_t* secondary = va_arg(ar, char32_t*);
+                if (!scts_append_mu(&primary, secondary)) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                break;
+            }
+                
+            case SCTS_INSERT: {
+                CHECK_INPUT_IS_STRING;
+                char32_t* secondary = va_arg(ar, char32_t*);
+                int where = va_arg(ar, int);
+                if (!scts_insert(&primary, secondary, where)) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                break;            
+            }
+            
+            case SCTS_JOIN: {
+                CHECK_INPUT_IS_STRING;
+                char32_t** l = va_arg(ar, char32_t**);
+                if (!scts_join(&primary, l)) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                break;            
+            }
+            
+            case SCTS_REPLACE: {
+                CHECK_INPUT_IS_STRING;
+                char32_t* target = va_arg(ar, char32_t*);
+                char32_t* replacement = va_arg(ar, char32_t*);
+                if (!scts_replace(&primary, target, replacement)) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                break;            
+            }
+            
+            case SCTS_SUBSTRING: {
+                CHECK_INPUT_IS_STRING;
+                int from = va_arg(ar, int);
+                int to = va_arg(ar, int);
+                if (!scts_substring(&primary, from, to)) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                break;                            
+            }
+            
+            // str -> list
+            case SCTS_SPLIT: {
+                CHECK_INPUT_IS_STRING;
+                char32_t *del = va_arg(ar, char32_t*);
+                
+                if (!(list = scts_split(primary, del))) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                
+                scts_free(primary);
+                last_output_type = type_list;
+                break;            
+            }
+            
+            
+            // list -> str
+            case SCTS_JOIN_LIST: {
+                CHECK_INPUT_IS_LIST;
+                primary = va_arg(ar, char32_t*);
+                if (!(primary = scts_new(primary))) {
+                    EPRINT("enternal error at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                if (!scts_join(&primary, list)) {
+                    EPRINT("broken flow at operation %d: ^", index);
+                    goto SUPER_ERROR;
+                }
+                scts_free(list);
+                last_output_type = type_string;
+                break;            
+            }
+
+            case SCTS_NTH: {
+                CHECK_INPUT_IS_LIST;
+                int n = va_arg(ar, int);
+                
+                if (n >= scta_length(list) || n < 0) {
+                    EPRINT("enternal error at operation %d: out of bonds: [%d] element of %d-element list requested.", index, n, scta_length(list));
+                    goto SUPER_ERROR;
+                }
+                primary = scts_new(list[n]);
+                scts_free(list);
+                last_output_type = type_string;
+                break;            
+            }
+            
+            // list -> list
+                
+                // -- filter
+                
+            // str -- flow control --> str
+            
+            
+        }
+    }
+    
+    SUPER_ERROR:
+    if (last_output_type == type_string) scts_free(primary);
+    else scts_free(list);
+    return NULL;
+    
+    SUPER_DONE:
+    if (last_output_type != type_string) {
+        EPRINT("flow terminates in a list which cannot be returned");
+        goto SUPER_ERROR;
+    }
+    // free temp list
+    return primary;
+}
+
+
+//TEST
+#ifdef test_flow
+
+#include <assert.h>
+#include <stdio.h>
+
+int main() {
+    /* 
+        add primitives
+        add proper tests
+        
+        commit git
+        
+        move print to io
+    */
+    
+    debug_fd = stderr;
+    char32_t *u, *v, *w;
+    char32_t *t = scts_flow_iu((u = scts_transcode("hel-yahoo-lo")), 
+        SCTS_SUBSTRING, 1, -2, 
+        SCTS_APPEND, (v=scts_transcode("ly")), 
+        SCTS_SPLIT, ((char32_t[]) {'-', 0}), 
+        SCTS_NTH, 1,
+        SCTS_SPLIT, ((char32_t[]) {'h', 0}), 
+        SCTS_JOIN_LIST, (w=scts_transcode("r")), 
+        SCTS_STOP);
+        
+    scts_print(stdout, t);
+    scts_free(t);
+    scts_free(u);
+    scts_free(v);
+    scts_free(w);
+    return 0;
+}
+
+#endif

modules/s/parts/init.c

 
 FILE* debug_fd = NULL;
 
-//TODO
-/*
-    - refactor codepoint.c
-    - rename debug_fd to sct_debug_fd and link to the rest of the library
-    - add proper const support
-    - //   //    restrict //
-    - format
-        < center >
-    - trim
-    - strip
-    - regex
-    - prathasis 
-    - 
-    
-*/

modules/s/parts/init.h

 extern FILE* debug_fd;
 
 // INTERNAL USE ONLY
+#define EPRINT(...) {\
+    if (debug_fd) {\
+        fprintf(debug_fd, "%s:%s():%d: ", __FILE__, __func__, __LINE__);\
+        fprintf(debug_fd, __VA_ARGS__);\
+        fprintf(debug_fd, "\n");\
+    }\
+}
+
 #define ERETURN(RET, ...) {\
     if (debug_fd) {\
         fprintf(debug_fd, "%s:%s():%d: ", __FILE__, __func__, __LINE__);\

modules/s/parts/join.c

     int total_length = 0;
     int total_count = 0;
     // input checks
-    if (!primary || !list) ERETURN(NULL, "null string supplied");
+    if (!primary || !list) ERETURN(NULL, "null string or list supplied");
     
     // logic
     

modules/s/parts/scts.h

 extern FILE* debug_fd;
 
 // INTERNAL USE ONLY
+#define EPRINT(...) {\
+    if (debug_fd) {\
+        fprintf(debug_fd, "%s:%s():%d: ", __FILE__, __func__, __LINE__);\
+        fprintf(debug_fd, __VA_ARGS__);\
+        fprintf(debug_fd, "\n");\
+    }\
+}
+
 #define ERETURN(RET, ...) {\
     if (debug_fd) {\
         fprintf(debug_fd, "%s:%s():%d: ", __FILE__, __func__, __LINE__);\
 #ifndef SCTS_PART_CODEPOINT
 #define SCTS_PART_CODEPOINT
 char32_t scts_codepoint(char *c);
-int scts_sequence_length_c(char *c);
-int scts_sequence_length_u(char32_t c);
-char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]);
+/*
+sctdoc:scts_codepoint:
 
-#define scts_sequence_length(primary) (_Generic( (0, primary), \
-    char32_t:scts_sequence_length_u, \
-    const char32_t:scts_sequence_length_u, \
-    char *: scts_sequence_length_c, \
-    const char *: scts_sequence_length_c \
-    )(primary))
+NAME
+    scts_codepoint
+
+SYNOPSIS
+    char32_t scts_codepoint(char *c);
     
+DESCRIPTION
+    This function returns the codepoint of the character sequence pointed to
+    by `c'.
+
+RETURN
+    This function returns the codepoint on success, and -1 sequince is 
+    ill-formed.
+
+EXAMPLE
+    scts_codepoint("٦") == 0x666;
+
+SEE ALSO
+    scts_sequence_codepoint
+    scts_sequence_length
+*/
+
 #endif
 
 
 
 
     
+//--flow
+#ifndef SCTS_PART_FLOW
+#define SCTS_PART_FLOW
+
+#define SCTS_STOP       (int) 0
+#define SCTS_APPEND     (int) 1
+#define SCTS_INSERT     (int) 2
+#define SCTS_JOIN       (int) 3
+#define SCTS_REPLACE    (int) 4
+#define SCTS_SPLIT      (int) 5
+#define SCTS_SUBSTRING  (int) 6
+#define SCTS_JOIN_LIST  (int) 7
+#define SCTS_NTH        (int) 8
+#define SCTS_COUNT      (int) 9
+
+char32_t* scts_flow_iu(char32_t *primary, ...);
+
+#define scts_flow(primary) (_Generic( (0, primary), \
+    char32_t *:         scts_flow_iu, \
+    char32_t **:        scts_flow_mu, \
+    const char32_t *:   scts_flow_iu, \
+    const char32_t **:  scts_flow_mu, \
+    char *:             scts_flow_ic, \
+    char **:            scts_flow_mc, \
+    const char *:       scts_flow_ic, \
+    const char **:      scts_flow_mc  \
+    )(primary))
+
+/*
+sctdoc:scts_flow:
+
+NAME
+    scts_flow
+
+SYNOPSIS
+    int generic_dummy([char*][char32_t*] primary)
+    
+    int generic_dummy_c(char *primary)
+    int generic_dummy_u(char32_t *primary)
+    
+DESCRIPTION
+    ...
+
+RETURN
+    ...
+
+EXAMPLE
+    ...
+
+SEE ALSO
+    ...
+*/
+
+#endif
+
+
+    
 //--insert
 #ifndef SCTS_PART_INSERT
 #define SCTS_PART_INSERT
 
 
     
+//--sequence_codepoint
+#ifndef SCTS_PART_SEQUENCE_CODEPOINT
+#define SCTS_PART_SEQUENCE_CODEPOINT
+char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]);
+/*
+sctdoc:scts_sequence_codepoint:
+
+NAME
+    scts_sequence_codepoint
+
+SYNOPSIS
+    char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5])
+    
+DESCRIPTION
+    This function is the inverse of scts_codepoint; it takes a codepoint and 
+    generates its sequenced representation. The second argument must be an 
+    array that can hold at least 5 elements.
+
+RETURN
+    This function returns `buf' on success, and NULL if `c' is an invalid 
+    codepoint.
+
+EXAMPLE
+    scts_sequence_codepoint(0x666, buf); // ==  "٦"
+
+SEE ALSO
+    scts_codepoint
+    scts_sequence_length
+*/
+
+#endif
+
+
+    
+//--sequence_length
+#ifndef SCTS_PART_SEQUENCE_LENGTH
+#define SCTS_PART_SEQUENCE_LENGTH
+int scts_sequence_length_c(char *c);
+int scts_sequence_length_u(char32_t c);
+#define scts_sequence_length(primary) (_Generic( (0, primary), \
+    char32_t:scts_sequence_length_u, \
+    const char32_t:scts_sequence_length_u, \
+    char *: scts_sequence_length_c, \
+    const char *: scts_sequence_length_c \
+    )(primary))
+
+/*
+sctdoc:scts_sequence_length:
+
+NAME
+    scts_sequence_length
+
+SYNOPSIS
+    int scts_sequence_length([char*][char32_t*] primary)
+    
+    int scts_sequence_length_c(char *c);
+    int scts_sequence_length_u(char32_t c);
+    
+DESCRIPTION
+    scts_sequence_length returns the number of bytes required to store a 
+    the utf8 representation of a given codepoint `c'.
+
+RETURN
+    This function returns a non-negative number upon success and -1 if the 
+    codepoint is not valid.
+
+EXAMPLE
+    scts_sequence_length("😻") == 4;
+
+SEE ALSO
+    scts_sequence_codepoint
+*/
+
+#endif
+
+
+    
 //--split
 #ifndef SCTS_PART_SPLIT
 #define SCTS_PART_SPLIT
     const char **:      scts_substring_mc  \
     )(primary, from, to))
 
+#define SCTS_EOS ((int)((~((unsigned int) 0))>>1)) //TODO switch to the standard def later
 
 /*
 sctdoc:scts_substring:
     Indices can be negative, indicating the location from the end of the 
     string.
     
-
+    SCTS_EOS is a special value that when passed as `to' denotes the end of the 
+    string.
+    
 RETURN
     If a mutable function is called, the function returns the substring pointer 
     that is stored in `primary', and NULL if an error occurs. `primary' will 
     // mutable = scts_new("سر فلا كبا بك الفرس")
     scts_substring(&mutable, 0, 3) // mutable == "سر "
     scts_substring(mutable,  0, 1) // mutable == "سر "; returns "س"
+    
+    // immutable = "سلام"
+    scts_substring(immutable, -1, SCTS_EOS) // ; returns "م"
 
 SEE ALSO
     scts_new

modules/s/parts/sequence_codepoint.c

+#include "scts.h"
+
+//HEADER
+#ifndef SCTS_PART_SEQUENCE_CODEPOINT
+#define SCTS_PART_SEQUENCE_CODEPOINT
+char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]);
+/*
+sctdoc:scts_sequence_codepoint:
+
+NAME
+    scts_sequence_codepoint
+
+SYNOPSIS
+    char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5])
+    
+DESCRIPTION
+    This function is the inverse of scts_codepoint; it takes a codepoint and 
+    generates its sequenced representation. The second argument must be an 
+    array that can hold at least 5 elements.
+
+RETURN
+    This function returns `buf' on success, and NULL if `c' is an invalid 
+    codepoint.
+
+EXAMPLE
+    scts_sequence_codepoint(0x666, buf); // ==  "٦"
+
+SEE ALSO
+    scts_codepoint
+    scts_sequence_length
+*/
+
+#endif
+
+//LIB
+char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]){
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    int size = scts_sequence_length(c);
+    
+    if (!size) ERETURN(NULL, "^");
+    
+    if (size == 1) {
+        buf[1] = 0;
+        buf[0] = c;
+    }
+    else if (size == 2) {
+        buf[2] = 0;
+        buf[1] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[0] = (c & 0x1f) | 0xc0;
+    }
+    else if (size == 3) {
+        buf[3] = 0;
+        buf[2] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[1] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[0] = (c & 0xf) | 0xe0;
+    }
+    else if (size == 4) {
+        buf[4] = 0;
+        buf[3] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[2] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[1] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[0] = (c & 0x7) | 0xf0;        
+    }
+    // If this occurs, something very wrong is happening in scts_byte_character_size
+    else ERETURN(NULL, "could not map codepoint to well-formed byte sequence"); 
+    
+    return buf;    
+}
+
+
+//TEST
+#ifdef test_sequence_codepoint
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+
+int main() {
+    debug_fd = stderr;
+    
+    char buf[5];
+    assert(!strcmp(scts_sequence_codepoint(0, buf), ""));
+    assert(!strcmp(scts_sequence_codepoint(0x666, buf), "٦"));
+    assert(!strcmp(scts_sequence_codepoint(0x23, buf), "#"));
+    assert(!strcmp(scts_sequence_codepoint(0xF906, buf), "句"));
+    assert(!strcmp(scts_sequence_codepoint(0x1F63B, buf), "😻"));
+    return 0;
+}
+
+#endif

modules/s/parts/sequence_length.c

+#include "scts.h"
+
+//HEADER
+#ifndef SCTS_PART_SEQUENCE_LENGTH
+#define SCTS_PART_SEQUENCE_LENGTH
+int scts_sequence_length_c(char *c);
+int scts_sequence_length_u(char32_t c);
+#define scts_sequence_length(primary) (_Generic( (0, primary), \
+    char32_t:scts_sequence_length_u, \
+    const char32_t:scts_sequence_length_u, \
+    char *: scts_sequence_length_c, \
+    const char *: scts_sequence_length_c \
+    )(primary))
+
+/*
+sctdoc:scts_sequence_length:
+
+NAME
+    scts_sequence_length
+
+SYNOPSIS
+    int scts_sequence_length([char*][char32_t*] primary)
+    
+    int scts_sequence_length_c(char *c);
+    int scts_sequence_length_u(char32_t c);
+    
+DESCRIPTION
+    scts_sequence_length returns the number of bytes required to store a 
+    the utf8 representation of a given codepoint `c'.
+
+RETURN
+    This function returns a non-negative number upon success and -1 if the 
+    codepoint is not valid.
+
+EXAMPLE
+    scts_sequence_length("😻") == 4;
+
+SEE ALSO
+    scts_sequence_codepoint
+*/
+
+#endif
+
+//LIB
+int scts_sequence_length_c(char *character){    
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    uint8_t * restrict c = (uint8_t *) character;
+    register int minlen = 0;
+    
+    if (!c) ERETURN(-1, "Null pointer");
+    
+    // assure that string is not abruptly short and get max max length posible if
+    // short. #security 
+    for (;c[minlen] && minlen < 5; ++minlen);
+    
+    // direct implementation of the spec.
+    if (c[0] >= 0x0 && c[0] <= 0x7f) {
+        return 1;
+    }
+    else if (c[0] >= 0xc2 && c[0] <=  0xdf && 
+                minlen >= 2 && c[1] >= 0x80 && c[1] <= 0xbf) {
+        return 2;   
+    }
+    else if (c[0] == 0xe0 && minlen >= 3 && 
+                c[1] >= 0xA0 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    }
+    else if (c[0] >= 0xe1 && c[0] <= 0xec && minlen >= 3 && 
+                c[1] >= 0x80 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    } 
+    else if (c[0] == 0xed && minlen >= 3 && 
+                c[1] >= 0x80 && c[1] <= 0x9f &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    }
+    else if (c[0] >= 0xee && c[0] <= 0xef && minlen >= 3 && 
+                c[1] >= 0x80 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    }
+    else if (c[0] == 0xf0 && minlen >= 4 && 
+                c[1] >= 0x90 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf &&
+                c[3] >= 0x80 && c[3] <= 0xbf ) {
+        return 4;   
+    }
+    else if (c[0] >= 0xf1 && c[0] <= 0xf3 && minlen >= 4 && 
+                c[1] >= 0x80 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf &&
+                c[3] >= 0x80 && c[3] <= 0xbf ) {
+        return 4;   
+    }
+    else if (c[0] == 0xf4 && minlen >= 4 && 
+                c[1] >= 0x80 && c[1] <= 0x8f &&
+                c[2] >= 0x80 && c[2] <= 0xbf &&
+                c[3] >= 0x80 && c[3] <= 0xbf ) {
+        return 4;   
+    }
+    else ERETURN(-1, "ill-formed byte sequence");
+}
+
+int scts_sequence_length_u(char32_t c){
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    #define else_range_return(start, end, ret) else if (c >= start && c <= end) return ret;
+    if (false) return 0;
+    else_range_return(0,        0x7f,       1)
+    else_range_return(0x80,     0x7ff,      2)
+    else_range_return(0x800,    0xfff,      3)
+    else_range_return(0x1000,   0xcfff,     3)
+    else_range_return(0xd000,   0xd7ff,     3)
+    else_range_return(0xe000,   0xffff,     3)
+    else_range_return(0x10000,  0x3ffff,    4)
+    else_range_return(0x40000,  0xfffff,    4)
+    else_range_return(0x100000, 0x10ffff,   4)
+    else ERETURN(-1, "None-valid codepoint: U+%lu", (unsigned long int) c);
+    #undef range_return
+}
+
+
+//TEST
+#ifdef test_sequence_length
+
+#include <assert.h>
+#include <stdio.h>
+
+int main() {
+    char *ltr;
+    debug_fd = stderr;
+    ltr = ""; assert(scts_sequence_length(ltr) == 1);
+    ltr = "s"; assert(scts_sequence_length(ltr) == 1);
+    ltr = "ﺔ"; assert(scts_sequence_length(ltr) == 3);
+    ltr = "س"; assert(scts_sequence_length(ltr) == 2);
+    ltr = "1"; assert(scts_sequence_length(ltr) == 1);
+    ltr = "句"; assert(scts_sequence_length(ltr) == 3);
+    ltr = "😻"; assert(scts_sequence_length(ltr) == 4);
+    
+    debug_fd = NULL;
+    assert(scts_sequence_length((char *) NULL) == (int) -1);
+    debug_fd = stderr;
+    
+    assert(scts_sequence_length((char32_t) 0x663) == 2);
+    assert(scts_sequence_length((char32_t) 0xa) == 1);
+    assert(scts_sequence_length((char32_t) 0xf906) == 3);
+    assert(scts_sequence_length((char32_t) 0x1F63B) == 4);
+    assert(scts_sequence_length((char32_t) 0) == 1);
+    
+    debug_fd = NULL;
+    assert(scts_sequence_length((char32_t) 0xffffff) == (int) -1);
+    assert(scts_sequence_length("\xE0\x9F\x80") == (int) -1);
+    debug_fd = stderr;
+}
+
+#endif

modules/s/parts/substring.c

     const char **:      scts_substring_mc  \
     )(primary, from, to))
 
+#define SCTS_EOS ((int)((~((unsigned int) 0))>>1)) //TODO switch to the standard def later
 
 /*
 sctdoc:scts_substring:
     Indices can be negative, indicating the location from the end of the 
     string.
     
-
+    SCTS_EOS is a special value that when passed as `to' denotes the end of the 
+    string.
+    
 RETURN
     If a mutable function is called, the function returns the substring pointer 
     that is stored in `primary', and NULL if an error occurs. `primary' will 
     // mutable = scts_new("سر فلا كبا بك الفرس")
     scts_substring(&mutable, 0, 3) // mutable == "سر "
     scts_substring(mutable,  0, 1) // mutable == "سر "; returns "س"
+    
+    // immutable = "سلام"
+    scts_substring(immutable, -1, SCTS_EOS) // ; returns "م"
 
 SEE ALSO
     scts_new
                                                  "bounds; supplied string length "
                                                  "is %d, effective `from' "
                                                  "value is %d", length, from);
-                                                 
+    if (to == SCTS_EOS) to = length;
     if (to < 0 || to < from || to > length) ERETURN(NULL,  
                                             "`to' paramater is out of bounds; "
                                             "supplied string length is %d, "
 int main() {
     debug_fd = stderr;
     char *test = "٠١٢٣٤٥٦٧٨٩";
-    char *c[10];
+    char *c[12];
     //
     assert(!strcmp(c[0]=scts_substring(test, 1, -1), "١٢٣٤٥٦٧٨"));
     assert(!strcmp(c[1]=scts_substring(test, 0, 0), ""));
-    assert(!strcmp(c[2]=scts_substring(test, 0, -9), "٠"));
-    assert(!strcmp(c[3]=scts_substring(test, -10, -9), "٠"));
-    assert(!strcmp(c[4]=scts_substring(test, 0, -10), ""));
-    assert(!strcmp(c[5]=scts_substring(test, 1, 1), ""));
-    assert(!strcmp(c[6]=scts_substring(test, 9, 10), "٩"));
-    assert(!strcmp(c[7]=scts_substring(test, -2, -1), "٨"));
-    assert(!strcmp(c[8]=scts_substring(test, 0, 1), "٠"));
+    assert(!strcmp(c[2]=scts_substring(test, 1, 1), ""));
+    assert(!strcmp(c[3]=scts_substring(test, 0, SCTS_EOS), "٠١٢٣٤٥٦٧٨٩"));
+    assert(!strcmp(c[4]=scts_substring(test, 0, -9), "٠"));
+    assert(!strcmp(c[5]=scts_substring(test, -10, -9), "٠"));
+    assert(!strcmp(c[6]=scts_substring(test, 0, -10), ""));
+    assert(!strcmp(c[7]=scts_substring(test, 1, 1), ""));
+    assert(!strcmp(c[8]=scts_substring(test, 9, 10), "٩"));
+    assert(!strcmp(c[9]=scts_substring(test, -2, -1), "٨"));
+    assert(!strcmp(c[10]=scts_substring(test, 0, 1), "٠"));
+    assert(!strcmp(c[11]=scts_substring(test, -1, SCTS_EOS), "٩"));
     
     debug_fd = NULL;
     assert(!scts_substring(test, 0, 11));
-    assert(!scts_substring(test, -11, 0));
+    assert(!scts_substring(test, -11, SCTS_EOS));
     assert(!scts_substring(test, 5, 4));
     assert(!scts_substring((char *) NULL, 0, 0));
     debug_fd = stderr;
     scts_free(c[6]);
     scts_free(c[7]);
     scts_free(c[8]);
+    scts_free(c[9]);
+    scts_free(c[10]);
+    scts_free(c[11]);
     
     // Testing mutable wrapper
     char *mutable = scts_new("سر فلا كبا بك الفرس");
+#include "scts.h"
+
+// STATIC SECTION
+#include <stdio.h>
+
+FILE* debug_fd = NULL;
+
+//TODO
 /*
+    - rename debug_fd to sct_debug_fd and link to the rest of the library
+    - add proper const support
+    - //   //    restrict //
+    - format
+        < center >
+    - trim
+    - strip
+    - regex
+    - prathasis 
+    
+*/
+char32_t* scts_append_iu(char32_t *primary, char32_t *secondary){
+    char32_t *out;
+    int length;
+    
+    if (!primary)  ERETURN(NULL, "null string supplied");
+    if ((length = scts_length(primary)) == -1) ERETURN(NULL, "malformed string supplied");
+    if (!(out = scts_insert_iu(primary, secondary, length))) ERETURN(NULL, "internal call failed");
+    
+    
+    return out;
+}
 
-    scts: Strings Module with builtin arabic support
+char32_t* scts_append_mu(char32_t **primary, char32_t *secondary){
+    char32_t *n;
+    
+    if (!primary || !(*primary) || !secondary)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_append_iu(*primary, secondary);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
 
-    Sulaiman (seininn) Mustafa     2014-03-31
+char* scts_append_ic(char *primary, char *secondary){
+    char32_t *n, *m;
     
-    This module is a part of libstc, a modular, c11-compliant, 
-    toolkit library. use stcmod to determine this module's 
-    dependencies, if any.
+    if (!primary || !secondary) ERETURN(NULL, "null string supplied");
     
-*/
+    n = scts_transcode(primary);
+    m = scts_transcode(secondary);
+    
+    if (!n) ERETURN(NULL, "could not transcode byte sequence");
+    if (!scts_append_mu(&n, m)) {
+        scts_free(n);
+        scts_free(m);
+        ERETURN(NULL, "internal call to mutable unicode counterpart failed");
+    }
+    primary = scts_transcode(n);
+    if (!primary) {
+        scts_free(n);
+        scts_free(m);
+        ERETURN(NULL, "internal library failure"); // should never fail to transcode happen unless something is broken
+    }
+    scts_free(n);
+    scts_free(m);
+    return primary;
+}
 
-#include <stdio.h>
-#include <stdlib.h>
+
+char* scts_append_mc(char **primary, char *secondary){
+    char *n;
+
+    if (!primary || !(*primary) || !secondary)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_append_ic(*primary, secondary);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+
+
+    
+int scts_cached_length(void *primary){
+    // input checks
+    if (!primary) return 0;
+    // logic
+    return scta_length(primary);
+}
+
+
+    
+char32_t scts_codepoint(char *c){
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    // (char32_t) -1 error could should be fine because it's not a valid code point
+    // validation and string length assertions are preformed in 
+    // byte_character_size
+    int size = scts_sequence_length(c);
+    if (size == -1) ERETURN(-1, "^");
+    
+    if (size == 1) return c[0];
+    else if (size == 2) {
+        return  (((char32_t) 0x1f & c[0]) << 6) | 
+                ((char32_t) 0x3f & c[1]) ;
+    }
+    else if (size == 3) {
+        return  (((char32_t) 0x0f & c[0]) << 12) | 
+                (((char32_t) 0x3f & c[1]) << 6) |
+                ((char32_t) 0x3f & c[2]) ;
+    }
+    else if (size == 4) {
+        return  (((char32_t) 0x07 & c[0]) << 18) | 
+                (((char32_t) 0x3f & c[1]) << 12) |
+                (((char32_t) 0x3f & c[2]) << 6) |
+                ((char32_t) 0x3f & c[3]);
+    }    
+    // If this occurs, something very wrong is happening in scts_byte_character_size
+    else ERETURN((char32_t) -1, "could not map codepoint to well-formed byte sequence"); 
+}
+
+
+
+    
 #include <string.h>
-#include <stdint.h>
-#include <limits.h>
+bool scts_equals_u(char32_t *primary, char32_t *secondary){
+    // input checks
+    if (!primary || !secondary) ERETURN(NULL, "null string supplied for the %s paramater", ((!primary)?"first":"second"));
+    // logic
+    for (register int i = 0; primary[i]; ++i) if (primary[i] != secondary[i]) return false;
+    return true;
+}
+
+bool scts_equals_c(char *primary, char *secondary){
+    // input checks
+    if (!primary || !secondary) ERETURN(NULL, "null string supplied for the %s paramater", ((!primary)?"first":"second"));
+    // logic
+    return (bool) !strcmp(primary, secondary);
+}
+
+
+    
+int scts_find_u(char32_t *restrict haystack, char32_t *restrict needle){
+    // input checks
+    if (!haystack || !needle) ERETURN(-1, "null string supplied for the %s paramater", ((!haystack)?"first":"second"));
+    
+    // logic
+    // nieve implimintation for now... add support later or maybe different function: scts_search?
+    if (!needle[0]) return -1; // definition: to be more inline with other string APIs
+    for (int i = 0; haystack[i]; ++i) {
+        int j = 0;
+        for (; haystack[i+j] == needle[j] && needle[j] != 0; ++j);
+        if (needle[j] == 0) return i;   
+        else i+=j;
+    }
+    return -1;
+}
+
+int scts_find_c(char *restrict haystack, char *restrict needle){
+    // input checks
+    if (!haystack || !needle) ERETURN(-1, "null string supplied for the %s paramater", ((!haystack)?"first":"second"));
+    
+    // logic
+    char32_t *h = scts_transcode(haystack);
+    char32_t *n = scts_transcode(needle);
+    
+    if (!h || !n) ERETURN(-1, "failed to transcode the %s paramater", ((!haystack)?"first":"second"));
+
+    int result = scts_find_u(h, n);
+    scts_free(h);
+    scts_free(n);
+    
+    return result;
+}
+
+
+
+    
+char32_t* scts_insert_iu(char32_t *primary, char32_t *secondary, int where){
+    // input checks
+    if (!primary || !secondary) ERETURN(NULL, "null string supplied");
+    
+    // logic
+    int primary_length = scts_length(primary);
+    int secondary_length = scts_length(secondary);
+    
+    if (primary_length == -1 || secondary_length == -1) ERETURN(NULL, "invalid string supplied");
+    
+    // if negative indexing is used
+    if (where < 0) where+=primary_length;
+    
+    // bound checks
+    if (where < 0 || where > primary_length) ERETURN(NULL, "`where' paramater is out of "
+                                                 "bounds; supplied string length "
+                                                 "is %d, effective `where' "
+                                                 "value is %d", primary_length, where);
+    
+    char32_t *out = scts_new(primary);
+    if (!out) ERETURN(NULL,  "Could not allocate memory for new string");
+    if (!scta_insert_array(out, where, secondary, secondary_length)) {
+        scts_free(out);
+        ERETURN(NULL,  "Could not complete insertion");
+    }
+    return out;
+}
+
+char32_t* scts_insert_mu(char32_t **primary, char32_t *secondary, int where){
+    char32_t *n;
+    
+    if (!primary || !(*primary) || !secondary)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_insert_iu(*primary, secondary, where);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+char* scts_insert_ic(char *primary, char *secondary, int where){
+    char32_t *n, *m;
+    
+    if (!primary || !secondary) ERETURN(NULL, "null string supplied");
+    
+    n = scts_transcode(primary);
+    m = scts_transcode(secondary);
+    
+    if (!n) ERETURN(NULL, "could not transcode byte sequence");
+    if (!scts_insert_mu(&n, m, where)) {
+        scts_free(n);
+        scts_free(m);
+        ERETURN(NULL, "internal call to mutable unicode counterpart failed");
+    }
+    primary = scts_transcode(n);
+    if (!primary) {
+        scts_free(n);
+        scts_free(m);
+        ERETURN(NULL, "internal library failure"); // should never fail to transcode happen unless something is broken
+    }
+    scts_free(n);
+    scts_free(m);
+    return primary;
+}
+
+
+char* scts_insert_mc(char **primary, char *secondary, int where){
+    char *n;
+
+    if (!primary || !(*primary) || !secondary)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_insert_ic(*primary, secondary, where);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+
+
+    
+char32_t* scts_join_iu(char32_t *primary, char32_t **list){
+    int total_length = 0;
+    int total_count = 0;
+    // input checks
+    if (!primary || !list) ERETURN(NULL, "null string supplied");
+    
+    // logic
+    
+    // if empty list, return empty string
+    if (!list[0]) return scts_new(((char32_t[]) {0}));
+    
+    // calculate total memory needed to join strings with primary
+    for (total_count = 0; list[total_count]; ++total_count) {
+        int temp;
+        if ((temp = scts_length(list[total_count])) == -1) ERETURN(NULL, "invalid string in `list'");
+        total_length += temp;
+    }
+    {// continued ^
+        int temp = scts_length(primary);
+        if (temp == -1) ERETURN(NULL, "`primary' is an invalid string")
+        total_length += temp*total_count;
+    }
+    
+    
+    // allocating string large enough to hold everything
+    char32_t *out = scta_new(char32_t);
+    if (!scta_set_length(out, total_length)) ERETURN(NULL, "memory reservation failure");
+    
+    { // copy stuff
+        int cur = 0;
+        for (int i = 0; i < total_count; ++i) {
+            for (int j = 0; list[i][j]; ++j) out[cur++] = list[i][j];
+            if (list[i+1]) for (int j = 0; primary[j]; ++j) out[cur++] = primary[j]; 
+        }
+    }
+    return out;   
+}
+
+char32_t* scts_join_mu(char32_t **primary, char32_t **list){
+    char32_t *n;
+    
+    if (!primary || !list)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_join_iu(*primary, list);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+char* scts_join_ic(char *primary, char **list){
+    char32_t *n, **m;
+    
+    if (!primary || !list) ERETURN(NULL, "null string supplied");
+    
+    n = scts_transcode(primary);
+    if (!n) ERETURN(NULL, "could not transcode byte sequence");
+    
+    if (!(m = scta_new(char32_t *))) ERETURN(NULL, "memory reservation failure");
+    for (int i = 0; list[i]; ++i) {
+        if (!scta_push(m, scts_transcode(list[i]))) ERETURN(NULL, "memory reservation failure");
+        if (m[scta_length(m)-1] == NULL) ERETURN(NULL, "could not transcode byte sequence");
+    }
+    
+    if (!scts_join_mu(&n, m)) {
+        scts_free(n);
+        scts_free(m);
+        ERETURN(NULL, "internal call to mutable unicode counterpart failed");
+    }
+    primary = scts_transcode(n);
+    if (!primary) {
+        scts_free(n);
+        scts_free(m);
+        ERETURN(NULL, "internal library failure"); // should never fail to transcode happen unless something is broken
+    }
+    scts_free(n);
+    scts_free(m);
+    return primary;
+}
+
+char* scts_join_mc(char **primary, char **list){
+    char *n;
+
+    if (!primary || !list)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_join_ic(*primary, list);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+    
+#include <string.h>
+
+int scts_legacy_length_c(char * restrict primary){
+    // input checks
+    if (!primary) return 0;
+    // logic
+    //TODO add checks #security
+    return strlen(primary);
+}
+
+int scts_legacy_length_u(char32_t * restrict primary){
+    register size_t temp = 0;
+    register size_t total = 0;
+    // input checks
+    if (!primary) return 0;
+    // logic
+
+    for (register size_t i = 0; primary[i]; ++i) {
+        if ((temp = scts_sequence_length(primary[i])) == -1) ERETURN(-1, "invalid codepoint detected %u", primary[i]);
+        total += temp;
+    }
+    return total;
+    
+}
+
+
+    
+#include <string.h>
+int scts_length_c(char * restrict primary){
+    register size_t i = 0;
+    register size_t j = 0;
+    // input checks
+    if (!primary) return 0;
+    // logic
+    while (primary[j]) {
+        register int s = scts_sequence_length(primary+j);
+        if (s == -1) ERETURN(-1, "^");
+        j += s;
+        ++i;
+    }
+    return i;
+    
+}
+int scts_length_u(char32_t * restrict primary){
+    register size_t i = 0;
+    // input checks
+    if (!primary) return 0;
+    // logic
+    while (primary[i]) {
+        if (scts_sequence_length(primary[i]) == -1) ERETURN(-1, "^");
+        ++i;
+    }
+    return i;
+}
+/*
+size_t scts_length_l(void ** restrict primary){
+    register size_t i = 0;
+    // input checks
+    if (!primary) return 0;
+    // logic
+    while (primary[i++]);
+    return i-1;
+}*/
+
+
+
+    
+#include <string.h> //TODO remove this, and replace all string library calls with scts 
+char* scts_new_c(char *primary){
+    // input checks
+    if (!primary) primary="";
+    // logic
+    char *out = scta_new(char);
+    if (!out) ERETURN(NULL, "failed to allocate memory new dynamic string.");
+    if (! scta_insert_array(out, 0, primary, scts_legacy_length(primary))) {
+        scta_free(out);
+        ERETURN(NULL, "failed to copy primary into dynamic string.");
+    }
+    return out;
+}
+
+
+char32_t* scts_new_u(char32_t *primary){
+    // input checks
+    if (!primary) primary= (char32_t[1]) {0}; //TODO use U syntax
+    // logic
+    char32_t *out = scta_new(char32_t);
+    if (!out) ERETURN(NULL, "failed to allocate memory new dynamic string.");
+    if (! scta_insert_array(out, 0, primary, scts_length(primary))) { 
+        scta_free(out);
+        ERETURN(NULL, "failed to copy primary into dynamic string.");
+    }
+    return out;
+}
+
+
+void scts_free_pointer(void *primary){
+    scta_free(primary);
+}
+
+void scts_free_list(void *primary){
+    void **p = (void **) primary;
+    for (int i = 0; p[i]; ++i) scta_free(p[i]);
+    scta_free(p);
+}
+
+
+
+    
+int scts_print_u(FILE *stream, char32_t* primary){
+    char seq[5];
+    int i = 0;
+    // input checks
+    if (!primary) ERETURN(-1, "cannot print NULL string");
+    // logic
+    for (i = 0; primary[i]; ++i) {
+        if (!scts_sequence_codepoint(primary[i], seq)) ERETURN(-1, "Could not sequence codepoint");
+        fputs(seq, stream);
+    }
+    return i;
+}
+
+int scts_print_c(FILE *stream, char* primary){
+    if (!primary) ERETURN(-1, "cannot print NULL string");
+    return fputs(primary, stream);
+}
+
+
+    
+
+char32_t* scts_replace_iu(char32_t *primary, char32_t *target, char32_t *replacement){
+    // input checks
+    if (!primary || !target || !replacement) ERETURN(NULL, "null string supplied");
+    // logic
+    //TODO Too slow: unwind and enterlance
+    int target_length = scts_length(target);
+    if (target_length == -1) ERETURN(NULL, "`target' is an invalid string");
+    
+    char32_t *out = scta_new(char32_t);
+    int i = 0;
+    while (true) {
+        int ti = scts_find(primary+i, target);
+        if (ti == -1) {
+            if (!scts_append(&out, primary+i)) ERETURN(NULL, "failed to append terminating part of string");
+            break;
+        }
+        else {
+            //TODO switch to scts_append_substring() or scts_insert_substring()            
+            char32_t *sub = scts_substring(primary+i, 0, ti);
+            if (!sub) {
+                scts_free(out);
+                ERETURN(NULL, "could not extract substring from `primary': [%d:%d]", i, i+ti);
+            }
+            if (!scts_append(&out, sub)) ERETURN(NULL, "failed to append initial part of string");
+            if (!scts_append(&out, replacement)) ERETURN(NULL, "failed to append replacement");
+            scts_free(sub);
+            i+=(ti+target_length);
+        }
+    }
+    return out;
+}
+
+char32_t* scts_replace_mu(char32_t **primary, char32_t *target, char32_t *replacement){
+    char32_t *n;
+    
+    if (!primary || !target || !replacement)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_replace_iu(*primary, target, replacement);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+char* scts_replace_ic(char *primary, char *target, char *replacement){
+    char32_t *n, *m, *l;
+    
+    if (!primary || !target) ERETURN(NULL, "null string supplied");
+    
+    n = scts_transcode(primary);
+    m = scts_transcode(target);
+    l = scts_transcode(replacement);
+    
+    if (!n) ERETURN(NULL, "could not transcode byte sequence");
+    if (!scts_replace_mu(&n, m, l)) {
+        scts_free(n);
+        scts_free(m);
+        scts_free(l);
+        ERETURN(NULL, "internal call to mutable unicode counterpart failed");
+    }
+    primary = scts_transcode(n);
+    if (!primary) {
+        scts_free(n);
+        scts_free(m);
+        scts_free(l);
+        ERETURN(NULL, "internal library failure"); // should never fail to transcode happen unless something is broken
+    }
+    scts_free(n);
+    scts_free(m);
+    scts_free(l);
+    return primary;
+}
+
+
+char* scts_replace_mc(char **primary, char *target, char *replacement){
+    char *n;
+
+    if (!primary || !(*primary) || !target)  ERETURN(NULL, "null string supplied");
+    
+    n = scts_replace_ic(*primary, target, replacement);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+
+
+    
+char* scts_sequence_codepoint(char32_t c, char buf[restrict static 5]){
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    int size = scts_sequence_length(c);
+    
+    if (!size) ERETURN(NULL, "^");
+    
+    if (size == 1) {
+        buf[1] = 0;
+        buf[0] = c;
+    }
+    else if (size == 2) {
+        buf[2] = 0;
+        buf[1] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[0] = (c & 0x1f) | 0xc0;
+    }
+    else if (size == 3) {
+        buf[3] = 0;
+        buf[2] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[1] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[0] = (c & 0xf) | 0xe0;
+    }
+    else if (size == 4) {
+        buf[4] = 0;
+        buf[3] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[2] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[1] = (c & 0x3f) | 0x80;
+        c>>=6;
+        buf[0] = (c & 0x7) | 0xf0;        
+    }
+    // If this occurs, something very wrong is happening in scts_byte_character_size
+    else ERETURN(NULL, "could not map codepoint to well-formed byte sequence"); 
+    
+    return buf;    
+}
 
-#include "scts.h"
-#include "scta.h"
 
 
-FILE *scts_config_debug = NULL;
-int scts_config_version[3] = {1, 1, 1};
+    
+int scts_sequence_length_c(char *character){    
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    uint8_t * restrict c = (uint8_t *) character;
+    register int minlen = 0;
+    
+    if (!c) ERETURN(-1, "Null pointer");
+    
+    // assure that string is not abruptly short and get max max length posible if
+    // short. #security 
+    for (;c[minlen] && minlen < 5; ++minlen);
+    
+    // direct implementation of the spec.
+    if (c[0] >= 0x0 && c[0] <= 0x7f) {
+        return 1;
+    }
+    else if (c[0] >= 0xc2 && c[0] <=  0xdf && 
+                minlen >= 2 && c[1] >= 0x80 && c[1] <= 0xbf) {
+        return 2;   
+    }
+    else if (c[0] == 0xe0 && minlen >= 3 && 
+                c[1] >= 0xA0 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    }
+    else if (c[0] >= 0xe1 && c[0] <= 0xec && minlen >= 3 && 
+                c[1] >= 0x80 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    } 
+    else if (c[0] == 0xed && minlen >= 3 && 
+                c[1] >= 0x80 && c[1] <= 0x9f &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    }
+    else if (c[0] >= 0xee && c[0] <= 0xef && minlen >= 3 && 
+                c[1] >= 0x80 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf ) {
+        return 3;   
+    }
+    else if (c[0] == 0xf0 && minlen >= 4 && 
+                c[1] >= 0x90 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf &&
+                c[3] >= 0x80 && c[3] <= 0xbf ) {
+        return 4;   
+    }
+    else if (c[0] >= 0xf1 && c[0] <= 0xf3 && minlen >= 4 && 
+                c[1] >= 0x80 && c[1] <= 0xbf &&
+                c[2] >= 0x80 && c[2] <= 0xbf &&
+                c[3] >= 0x80 && c[3] <= 0xbf ) {
+        return 4;   
+    }
+    else if (c[0] == 0xf4 && minlen >= 4 && 
+                c[1] >= 0x80 && c[1] <= 0x8f &&
+                c[2] >= 0x80 && c[2] <= 0xbf &&
+                c[3] >= 0x80 && c[3] <= 0xbf ) {
+        return 4;   
+    }
+    else ERETURN(-1, "ill-formed byte sequence");
+}
 
-#define ERRMSG_AND_RETURN(RET, ...) {\
-    if (scta_config_debug) {\
-        fprintf(scta_config_debug, "scta:%s():%d: ", __func__, __LINE__);\
-        fprintf(scta_config_debug, __VA_ARGS__);\
-        fprintf(scta_config_debug, "\n");\
-    }\
-    return (RET); \
+int scts_sequence_length_u(char32_t c){
+    // Unicode Standard 6.2: Section 3.9: Page 95
+    #define else_range_return(start, end, ret) else if (c >= start && c <= end) return ret;
+    if (false) return 0;
+    else_range_return(0,        0x7f,       1)
+    else_range_return(0x80,     0x7ff,      2)
+    else_range_return(0x800,    0xfff,      3)
+    else_range_return(0x1000,   0xcfff,     3)
+    else_range_return(0xd000,   0xd7ff,     3)
+    else_range_return(0xe000,   0xffff,     3)
+    else_range_return(0x10000,  0x3ffff,    4)
+    else_range_return(0x40000,  0xfffff,    4)
+    else_range_return(0x100000, 0x10ffff,   4)
+    else ERETURN(-1, "None-valid codepoint: U+%lu", (unsigned long int) c);
+    #undef range_return
 }
 
-const char* EXAMPLE_cc(const char **s){
 
+
+    
+char32_t** scts_split_u(char32_t *restrict primary, char32_t *restrict delemeter){
+    // input checks
+    if (!primary || !delemeter) ERETURN(NULL, "null string supplied for the %s paramater", ((!primary)?"first":"second"));
+    
+    // logic
+    int i = 0, where;
+    int length = scts_length(delemeter);
+    if (length == -1) ERETURN(NULL, "^");
+    char32_t **out = scta_new(char32_t *);
+    char32_t *shard;
+    
+    if (!out) ERETURN(NULL, "^");
+
+    while (true) {
+        where = scts_find(primary+i, delemeter);
+        
+        if (where != -1) shard = scts_substring(primary+i, 0, where);
+        else shard = scts_new(primary+i);
+
+        if (!shard) {
+            scts_free(out);
+            ERETURN(NULL, "^");
+        }
+        if (!scta_push(out, shard)) {
+            scts_free(out);
+            ERETURN(NULL, "^");
+        }
+        
+        if (where == -1) break;
+        i += (where+length);
+    }
+    
+    return out;
 }
-char* EXAMPLE_vc(char **s){
 
+char** scts_split_c(char *restrict primary, char *restrict delemeter){
+    // input checks
+    if (!primary || !delemeter) ERETURN(NULL, "null string supplied for the %s paramater", ((!primary)?"first":"second"));
+    
+    //TODO redo using string.h functions; no need to be unicode aware here
+    //TODO add custom tests for _u 
+    char32_t *p = scts_transcode(primary);
+    char32_t *s = scts_transcode(delemeter);
+    char32_t **o = scts_split_u(p, s);
+    if (!o) ERETURN(NULL, "split failed");
+    char **out = scta_new(char *);
+    scta_set_length(out, scta_length(o));
+    for (int i = 0; o[i]; ++i) out[i] = scts_transcode(o[i]);
+    scts_free(p);
+    scts_free(s);
+    scts_free(o);
+    return out;
 }
-const uint32_t* EXAMPLE_cu(const uint32_t **s){
 
+
+
+    
+char32_t* scts_substring_iu(char32_t *primary, int from, int to){
+    // input checks
+    if (!primary) ERETURN(NULL, "null string supplied");
+    // logic
+    int length = scts_length(primary);
+    
+    // if negative indexing is used
+    if (from < 0) from+=length;
+    if (to < 0) to+=length;
+    
+    // bound checks
+    if (from < 0 || from > length) ERETURN(NULL, "`from' paramater is out of "
+                                                 "bounds; supplied string length "
+                                                 "is %d, effective `from' "
+                                                 "value is %d", length, from);
+                                                 
+    if (to < 0 || to < from || to > length) ERETURN(NULL,  
+                                            "`to' paramater is out of bounds; "
+                                            "supplied string length is %d, "
+                                            "effective `from' value is %d, "
+                                            "and effective `to' value is %d", 
+                                            length, from, to);
+    
+    // get a new string that is large enough to hold the substring
+    char32_t *out = scta_new(char32_t);
+    if (!out) ERETURN(NULL,  "Could not allocate memory for new string");
+    if (!scta_set_length(out, to-from)) {
+        scts_free(out);
+        ERETURN(NULL,  "Could not allocate memory for new string length %d", to-from);
+    }
+    
+    for (register int i = from; i != to; ++i) out[i-from] = primary[i];
+    return out;
 }
-uint32_t* EXAMPLE_vu(uint32_t **s){
+
+char32_t* scts_substring_mu(char32_t **primary, int from, int to){
+    char32_t *n;
     
+    if (!primary || !(*primary))  ERETURN(NULL, "null string supplied");
+    
+    n = scts_substring_iu(*primary, from, to);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+char* scts_substring_ic(char *primary, int from, int to){
+    char32_t *n;
+    
+    if (!primary) ERETURN(NULL, "null string supplied");
+    
+    n = scts_transcode(primary);
+    if (!n) ERETURN(NULL, "could not transcode byte sequence");
+    if (!scts_substring_mu(&n, from, to)) {
+        scts_free(n);
+        ERETURN(NULL, "internal call to mutable unicode counterpart failed");
+    }
+    primary = scts_transcode(n);
+    if (!primary) {
+        scts_free(n);
+        ERETURN(NULL, "internal library failure"); // should never fail to transcode happen unless something is broken
+    }
+    scts_free(n);
+    return primary;
+}
+
+char* scts_substring_mc(char **primary, int from, int to){
+    char *n;
+
+    if (!primary || !(*primary))  ERETURN(NULL, "null string supplied");
+    
+    n = scts_substring_ic(*primary, from, to);
+    if (!n) ERETURN(NULL, "internal call to imutable counterpart failed");
+    scts_free(*primary);
+    *primary = n;
+    return n;
+}
+
+
+    
+char32_t* scts_transcode_c(char * restrict primary){
+    // note: scta always terminates an array with a null/0
+    //       that's why strings are not terminated here. #security
+    
+    // input checks
+    if (!primary) primary = "";
+    // logic