gdiff 0.0.1

data/ext/gdiff/sarray.c

@@ -0,0 +1,372 @@
+/*
+Hybrid suffix-array builder, written by Sean Quinlan and Sean Doward,
+distributed under the Plan 9 license, which reads in part
+
+3.3 With respect to Your distribution of Licensed Software (or any
+portion thereof), You must include the following information in a
+conspicuous location governing such distribution (e.g., a separate
+file) and on all copies of any Source Code version of Licensed
+Software You distribute:
+
+    "The contents herein includes software initially developed by
+    Lucent Technologies Inc. and others, and is subject to the terms
+    of the Lucent Technologies Inc. Plan 9 Open Source License
+    Agreement.  A copy of the Plan 9 Open Source License Agreement is
+    available at: http://plan9.bell-labs.com/plan9dist/download.html
+    or by contacting Lucent Technologies at http: //www.lucent.com.
+    All software distributed under such Agreement is distributed on,
+    obligations and limitations under such Agreement.  Portions of
+    the software developed by Lucent Technologies Inc. and others are
+    Copyright (c) 2002.  All rights reserved.
+    Contributor(s):___________________________"
+*/
+/*	
+	int sarray(int a[], int n)
+Purpose
+	Return in a[] a suffix array for the original
+	contents of a[].  (The original values in a[]
+	are typically serial numbers of distinct tokens
+	in some list.)
+
+Precondition
+	Array a[] holds n values, with n>=1.  Exactly k 
+	distinct values, in the range 0..k-1, are present.
+	Value 0, an endmark, appears exactly once, at a[n-1].
+
+Postcondition
+	Array a[] is a copy of the internal array p[]
+	that records the sorting permutation: if i<j
+	then the original suffix a[p[i]..n-1] is
+	lexicographically less than a[p[j]..n-1].
+
+Return value
+	-1 on error.
+	Otherwise index i such that a[i]==0, i.e. the
+        index of the whole-string suffix, used in
+	Burrows-Wheeler data compression.
+*/
+
+#include <stdlib.h>
+#include <string.h>
+#include "sarray.h"
+
+#define pred(i, h) ((t=(i)-(h))<0?  t+n: t)
+#define succ(i, h) ((t=(i)+(h))>=n? t-n: t)
+
+enum
+{
+	BUCK = ~(~0u>>1),	/* high bit */
+	MAXI = ~0u>>1,		/* biggest int */
+};
+
+static	void	qsort2(int*, int*, int n);
+static	int	ssortit(int a[], int p[], int n, int h, int *pe, int nbuck);
+
+int
+sarray(int a[], int n)
+{
+	int i, l;
+	int c, cc, ncc, lab, cum, nbuck;
+	int k;
+	int *p = 0;
+	int result = -1;
+	int *al;
+	int *pl;
+
+	for(k=0,i=0; i<n; i++)	
+		if(a[i] > k)
+			k = a[i];	/* max element */
+	k++;
+	if(k>n)
+		goto out;
+
+	nbuck = 0;
+	p = malloc(n*sizeof(int));
+	if(p == 0)
+		goto out;
+
+
+	pl = p + n - k;
+	al = a;
+	memset(pl, -1, k*sizeof(int));
+
+	for(i=0; i<n; i++) {		/* (1) link */
+		l = a[i];
+		al[i] = pl[l];
+		pl[l] = i;
+	}
+
+	for(i=0; i<k; i++)		/* check input - no holes */
+		if(pl[i]<0)
+			goto out;
+
+	
+	lab = 0;			/* (2) create p and label a */
+	cum = 0;
+	i = 0;
+	for(c = 0; c < k; c++){	
+		for(cc = pl[c]; cc != -1; cc = ncc){
+			ncc = al[cc];
+			al[cc] = lab;
+			cum++;
+			p[i++] = cc;
+		}
+		if(lab + 1 == cum) {
+			i--;
+		} else {
+			p[i-1] |= BUCK;
+			nbuck++;
+		}
+		lab = cum;
+	}
+
+	result = ssortit(a, p, n, 1, p+i, nbuck);
+	memcpy(a, p, n*sizeof(int));
+	
+out:
+	free(p);
+	return result;
+}
+
+/* bsarray(uchar buf[], int p[], int n)
+ * The input, buf, is an arbitrary byte array of length n.
+ * The input is copied to temporary storage, relabeling 
+ * pairs of input characters and appending a unique end marker 
+ * having a value that is effectively less than any input byte.
+ * The suffix array of this extended input is computed and
+ * stored in p, which must have length at least n+1.
+ *
+ * Returns the index of the identity permutation (regarding
+ * the suffix array as a list of circular shifts),
+ * or -1 if there was an error.
+ */
+int
+bsarray(const uchar buf[], int p[], int n)
+{
+	int *a, buckets[256*256];
+	int i, last, cum, c, cc, ncc, lab, id, nbuck;
+
+	a = malloc((n+1)*sizeof(int));
+	if(a == 0)
+		return -1;
+
+
+	memset(buckets, -1, sizeof(buckets));
+	c = buf[n-1] << 8;
+	last = c;
+	for(i = n - 2; i >= 0; i--){
+		c = (buf[i] << 8) | (c >> 8);
+		a[i] = buckets[c];
+		buckets[c] = i;
+	}
+
+	/*
+	 * end of string comes before anything else
+	 */
+	a[n] = 0;
+
+	lab = 1;
+	cum = 1;
+	i = 0;
+	nbuck = 0;
+	for(c = 0; c < 256*256; c++) {
+		/*
+		 * last character is followed by unique end of string
+		 */
+		if(c == last) {
+			a[n-1] = lab;
+			cum++;
+			lab++;
+		}
+
+		for(cc = buckets[c]; cc != -1; cc = ncc) {
+			ncc = a[cc];
+			a[cc] = lab;
+			cum++;
+			p[i++] = cc;
+		}
+		if(lab == cum)
+			continue;
+		if(lab + 1 == cum)
+			i--;
+		else {
+			p[i - 1] |= BUCK;
+			nbuck++;
+		}
+		lab = cum;
+	}
+
+	id = ssortit(a, p, n+1, 2, p+i, nbuck);
+	free(a);
+	return id;
+}
+
+static int
+ssortit(int a[], int p[], int n, int h, int *pe, int nbuck)
+{
+	int *s, *ss, *packing, *sorting;
+	int v, sv, vv, packed, lab, t, i;
+
+	for(; h < n && p < pe; h=2*h) {
+		packing = p;
+		nbuck = 0;
+
+		for(sorting = p; sorting < pe; sorting = s){
+			/*
+			 * find length of stuff to sort
+			 */
+			lab = a[*sorting];
+			for(s = sorting; ; s++) {
+				sv = *s;
+				v = a[succ(sv & ~BUCK, h)];
+				if(v & BUCK)
+					v = lab;
+				a[sv & ~BUCK] = v | BUCK;
+				if(sv & BUCK)
+					break;
+			}
+			*s++ &= ~BUCK;
+			nbuck++;
+
+			qsort2(sorting, a, s - sorting);
+
+			v = a[*sorting];
+			a[*sorting] = lab;
+			packed = 0;
+			for(ss = sorting + 1; ss < s; ss++) {
+				sv = *ss;
+				vv = a[sv];
+				if(vv == v) {
+					*packing++ = ss[-1];
+					packed++;
+				} else {
+					if(packed) {
+						*packing++ = ss[-1] | BUCK;
+					}
+					lab += packed + 1;
+					packed = 0;
+					v = vv;
+				}
+				a[sv] = lab;
+			}
+			if(packed) {
+				*packing++ = ss[-1] | BUCK;
+			}
+		}
+		pe = packing;
+	}
+
+	/*
+	 * reconstuct the permutation matrix
+	 * return index of the entire string
+	 */
+	v = a[0];
+	for(i = 0; i < n; i++)
+		p[a[i]] = i;
+
+	return v;
+}
+
+/*
+ * qsort from Bentley and McIlroy, Software--Practice and Experience
+   23 (1993) 1249-1265, specialized for sorting permutations based on
+   successors
+ */
+static void
+vecswap2(int *a, int *b, int n)
+{
+	while (n-- > 0) {
+        	int t = *a;
+		*a++ = *b;
+		*b++ = t;
+	}
+}
+
+#define swap2(a, b) { t = *(a); *(a) = *(b); *(b) = t; }
+
+static int*
+med3(int *a, int *b, int *c, int *asucc)
+{
+	int va, vb, vc;
+
+	if ((va=asucc[*a]) == (vb=asucc[*b]))
+		return a;
+	if ((vc=asucc[*c]) == va || vc == vb)
+		return c;	   
+	return va < vb ?
+		  (vb < vc ? b : (va < vc ? c : a))
+		: (vb > vc ? b : (va < vc ? a : c));
+}
+
+static void
+inssort(int *a, int *asucc, int n)
+{
+	int *pi, *pj, t;
+
+	for (pi = a + 1; --n > 0; pi++)
+		for (pj = pi; pj > a; pj--) {
+			if(asucc[pj[-1]] <= asucc[*pj])
+				break;
+			swap2(pj, pj-1);
+		}
+}
+
+static void
+qsort2(int *a, int *asucc, int n)
+{
+	int d, r, partval;
+	int *pa, *pb, *pc, *pd, *pl, *pm, *pn, t;
+
+	if (n < 15) {
+		inssort(a, asucc, n);
+		return;
+	}
+	pl = a;
+	pm = a + (n >> 1);
+	pn = a + (n-1);
+	if (n > 30) { /* On big arrays, pseudomedian of 9 */
+		d = (n >> 3);
+		pl = med3(pl, pl+d, pl+2*d, asucc);
+		pm = med3(pm-d, pm, pm+d, asucc);
+		pn = med3(pn-2*d, pn-d, pn, asucc);
+	}
+	pm = med3(pl, pm, pn, asucc);
+	swap2(a, pm);
+	partval = asucc[*a];
+	pa = pb = a + 1;
+	pc = pd = a + n-1;
+	for (;;) {
+		while (pb <= pc && (r = asucc[*pb]-partval) <= 0) {
+			if (r == 0) {
+				swap2(pa, pb);
+				pa++;
+			}
+			pb++;
+		}
+		while (pb <= pc && (r = asucc[*pc]-partval) >= 0) {
+			if (r == 0) {
+				swap2(pc, pd);
+				pd--;
+			}
+			pc--;
+		}
+		if (pb > pc)
+			break;
+		swap2(pb, pc);
+		pb++;
+		pc--;
+	}
+	pn = a + n;
+	r = pa-a;
+	if(pb-pa < r)
+		r = pb-pa;
+	vecswap2(a, pb-r, r);
+	r = pn-pd-1;
+	if(pd-pc < r)
+		r = pd-pc;
+	vecswap2(pb, pn-r, r);
+	if ((r = pb-pa) > 1)
+		qsort2(a, asucc, r);
+	if ((r = pd-pc) > 1)
+		qsort2(a + n-r, asucc, r);
+}

data/ext/gdiff/sarray.h

@@ -0,0 +1,13 @@
+#ifndef sarray_h
+#define sarray_h
+
+
+typedef unsigned char uchar;
+
+int sarray(int *a, int n);
+int bsarray(const uchar *b, int *a, int n);
+int *lcp(const int *a, const char *s, int n);
+int lcpa(const int *a, const char *s, int *b, int n);
+
+#endif
+

data/ext/gdiff/suffix_array.c

@@ -0,0 +1,510 @@
+#include <ruby.h>
+#include <assert.h>
+#include <sarray.h>
+
+typedef struct SuffixArray {
+    int *suffix_index;
+    unsigned int ends[256];
+    unsigned int starts[256];
+} SuffixArray;
+
+
+#define ERR_NO_ZERO_LENGTH_INPUT "Cannot create a suffix array from a 0 length input source."
+#define ERR_NOT_INITIALIZED "Initialization failed, you cannot use this object."
+#define ERR_START_IF_ARRAY "You must provide a start argument if you give an array argument."
+#define ERR_MISMATCH_LENGTH "The raw array length is different from the source length"
+static VALUE cSAError;
+
+
+inline int scan_string(unsigned char *source, size_t src_len, 
+                          unsigned char *target, size_t *tgt_len)
+{
+    size_t target_i = 0;
+    size_t source_i = 0;
+    size_t length = 0;
+    
+    while(target_i < *tgt_len && source_i < src_len && target[target_i] == source[source_i]) {
+        length++;
+        target_i++;
+        source_i++;
+    }
+    
+
+    if(target_i == *tgt_len) {
+        // found a match that's at least as long as the target, so good enough
+        *tgt_len = length;  // out parameter for the length that was found
+        return 0;
+    } else {
+        // target and source characters are now different, return that difference 
+        *tgt_len = length;  // out parameter for the length that was found
+        return  target[target_i] - source[source_i];
+    }
+    
+}
+
+
+size_t find_longest_match(unsigned char *source, size_t src_len, 
+                          unsigned char *target, size_t *tgt_len, 
+                          unsigned int starts[], unsigned int ends[], unsigned int sa[]) 
+{
+    size_t high = ends[*target] + 1;
+    size_t low = starts[*target];
+    size_t middle = (low + high) / 2;  // middle is pre-calculated so the while loop can exit
+    size_t length = 0;
+    size_t scan_len = 0;
+    size_t src_i = 0;
+    int result = 0;
+    size_t last_match = 0;
+    
+    while(low <= high && high <= src_len && middle < src_len && length != *tgt_len) {
+        src_i = sa[middle];
+        scan_len = *tgt_len;
+        
+        result = scan_string(source + src_i, src_len - src_i, target, &scan_len);
+        
+        if(scan_len > length)  {
+            length = scan_len;
+            last_match = middle;
+        }
+        
+        if(result == 0)
+            // found it so we're done
+            break;
+        else if(result < 0) {
+            // it's less than our current mid-point so drop down
+            high = middle - 1;
+        } else {
+            // it's greater than our current mid-point so push up
+            low = middle + 1;
+        }        
+
+        // recalculate the middle
+        middle = (low + high) / 2;
+    }
+        
+    // if we get here than it isn't found so break out
+    size_t start = sa[last_match];
+    *tgt_len = length;
+    return start;
+}
+
+
+/*
+ * call-seq:
+ *    sarray.source -> String
+ * 
+ * Returns the source that this suffix array was constructed with.
+ */
+static VALUE SuffixArray_source(VALUE self)
+{
+    return rb_iv_get(self, "@source");
+}
+    
+
+
+static void SuffixArray_free(void *p) {
+    SuffixArray *sa = (SuffixArray *)p;
+    if(sa->suffix_index) free(sa->suffix_index);
+    if(sa) free(sa);
+}
+
+static VALUE SuffixArray_alloc(VALUE klass)
+{
+    SuffixArray *sa = NULL;
+    
+    // setup our internal memory for the suffix array structure
+    return Data_Make_Struct(klass, SuffixArray, 0, SuffixArray_free, sa);
+}
+
+
+/*
+ * call-seq:
+ *   SuffixArray.new(source, [raw_array], [start]) -> SuffixArray
+ * 
+ * Given a string (anything like a string really) this will generate a
+ * suffix array for the string so that you can work with it.  The
+ * source cannot be an empty string since this is a useless operation.
+ *
+ * Two optional parameters allow you to restore a suffix array without
+ * running the construction process again.  You basically give it the
+ * String from SuffixArray.raw_array and the start from SuffixArray.suffix_start
+ * and it will skip most calculations.  <b>This feature is really experimental
+ * and is CPU dependent since the integers in the raw_array are native.</b>
+ */
+static VALUE SuffixArray_initialize(int argc, VALUE *argv, VALUE self)
+{
+    SuffixArray *sa = NULL;
+    size_t i = 0;
+    Data_Get_Struct(self, SuffixArray, sa);
+    assert(sa != NULL);
+    VALUE source;
+    VALUE array;
+    VALUE start;
+    
+    // sort out the arguments and such
+    rb_scan_args(argc, argv, "12", &source, &array, &start);
+
+    // get the string value of the source given to us, keep it around for later
+    VALUE sa_source_str = StringValue(source);
+    rb_iv_set(self, "@source", sa_source_str);
+    
+    // setup temporary variables for the source and length pointers
+    unsigned char *sa_source = RSTRING(sa_source_str)->ptr;
+    size_t sa_source_len = RSTRING(sa_source_str)->len;
+    
+    // error check the whole thing
+    if(sa_source_len == 0) {
+        // we can't have this, so return a nil
+        rb_raise(cSAError, ERR_NO_ZERO_LENGTH_INPUT);
+    }
+    
+    if(!NIL_P(array) && NIL_P(start)) {
+        rb_raise(cSAError, ERR_START_IF_ARRAY);
+    } else if (!NIL_P(array) && !NIL_P(start)) {
+        // looks like both parameters were given so check out the lengths
+        if(RSTRING(array)->len / sizeof(int) != sa_source_len) {
+            rb_raise(cSAError, ERR_MISMATCH_LENGTH);
+        }
+    }
+        
+    // allocate memory for the index integers
+    sa->suffix_index = malloc(sizeof(int) * (sa_source_len + 1));
+    
+    if(NIL_P(array)) {
+        // create the suffix array from the source
+        int st = bsarray(sa_source, sa->suffix_index, sa_source_len-1);
+
+        // set the suffix_start in our object
+        rb_iv_set(self, "@suffix_start", INT2NUM(st));
+    } else {
+        // convert the given array and start to the internal structures needed
+        // the return value is ignored since I can't seem find any consistent definition for
+        // it's value that will tell me if this failed.
+        memcpy(sa->suffix_index, RSTRING(array)->ptr, sa_source_len * sizeof(int));
+        rb_iv_set(self, "@suffix_start", start);
+    }
+    
+    unsigned char c = sa_source[sa->suffix_index[0]];  // start off with the first char in the sarray list
+    sa->starts[c] = 0;
+    for(i = 0; i < sa_source_len; i++) {
+        // skip characters until we see a new one
+        if(sa_source[sa->suffix_index[i]] != c) {
+            sa->ends[c] = i-1; // it's -1 since this is a new character, so the end was actually behind this point
+            c = sa_source[sa->suffix_index[i]];
+            sa->starts[c] = i;
+        }
+    }
+    // set the last valid character to get the tail of the sa, the loop will miss it
+    c = sa_source[sa->suffix_index[sa_source_len-1]];
+    sa->ends[c] = sa_source_len-1;
+    
+    return INT2FIX(sa_source_len);
+}
+
+
+/*
+ * call-seq:
+ *   sarray.longest_match(target, from_index) -> [start, length]
+ *
+ * Takes a target string and an index inside that string, and then tries
+ * to find the longest match from that point in the source string for this
+ * SuffixArray object.
+ * 
+ * It returns an array of [start, length] of where in the source a length
+ * string from the target would match.
+ *
+ * Refer to the unit test for examples of usage.
+ */
+static VALUE SuffixArray_longest_match(VALUE self, VALUE target, VALUE from_index) 
+{
+    SuffixArray *sa = NULL;
+    Data_Get_Struct(self, SuffixArray, sa);
+
+    VALUE sa_source = SuffixArray_source(self);
+    
+    if(sa == NULL || sa->suffix_index == NULL || RSTRING(sa_source)->len == 0) {
+        rb_raise(cSAError, ERR_NOT_INITIALIZED);
+    }
+    
+    // get the from and for_length arguments as unsigned ints
+    size_t from = NUM2UINT(from_index);
+
+    
+    // get better pointers for the source (should already be in String form)
+    unsigned char *source_ptr = RSTRING(sa_source)->ptr;
+    size_t source_len = RSTRING(sa_source)->len;
+
+    // get the target as a string
+    VALUE target_str = StringValue(target);
+    
+    // better pointers again, we also need target_len as an in/out parameter
+    unsigned char *target_ptr = RSTRING(target_str)->ptr;
+    size_t target_len = RSTRING(target_str)->len;
+
+    // check the input for validity, returning nil like in array operations
+    if(from > target_len) {
+        return Qnil;
+    }
+    
+    // adjust for the from and for_length settings to be within the target len
+    target_ptr += from;
+    target_len -= from;
+    
+    size_t start = find_longest_match(source_ptr, source_len, target_ptr, &target_len, 
+                                      sa->starts, sa->ends, sa->suffix_index);
+    
+    // create the 2 value return array
+    VALUE result = rb_ary_new();
+    
+    rb_ary_push(result, INT2FIX(start));
+    rb_ary_push(result, INT2FIX(target_len));
+    
+    return result;
+}
+
+
+/*
+ * call-seq:
+ *   sarray.longest_nonmatch(target, from_index, min_match) -> [non_match_length, match_start, match_length]
+ *
+ * Mostly the inverse of longest_match, except that it first tries to find a
+ * non-matching region, then a matching region.  The target and from_index are
+ * the same as in longest_match.  The min_match argument is the smallest matching
+ * region that you'll accept as significant enough to end the non-matching search.
+ * Giving non_match=0 will stop at the first matching region.
+ *
+ * It works by first searching the suffix array for a non-matching region.  When it 
+ * hits a character that is in the source (according to the suffix array) it tries
+ * to find a matching region.  If it can find a matching region that is longer than min_match
+ * then it stops and returns, otherwise it adds this match to the length of the non-matching
+ * region and continues.
+ *
+ * The return value is an Array of [non_match_length, match_start, match_length].
+ */
+static VALUE SuffixArray_longest_nonmatch(VALUE self, VALUE target, VALUE from_index, VALUE min_match) 
+{
+    SuffixArray *sa = NULL;
+    Data_Get_Struct(self, SuffixArray, sa);
+
+    VALUE sa_source = SuffixArray_source(self);
+    
+    if(sa == NULL || sa->suffix_index == NULL || RSTRING(sa_source)->len == 0) {
+        rb_raise(cSAError, ERR_NOT_INITIALIZED);
+    }
+    
+    // get the from and for_length arguments as unsigned ints
+    size_t from = NUM2UINT(from_index);
+    size_t min = NUM2INT(min_match);
+    
+    // get better pointers for the source (should already be in String form)
+    unsigned char *source_ptr = RSTRING(sa_source)->ptr;
+    size_t source_len = RSTRING(sa_source)->len;
+
+    // get the target as a string
+    VALUE target_str = StringValue(target);
+    
+    // better pointers again, we also need target_len as an in/out parameter
+    unsigned char *target_ptr = RSTRING(target_str)->ptr;
+    size_t target_len = RSTRING(target_str)->len;
+
+    // check the input for validity, returning nil like in array operations
+    if(from > target_len) {
+        return Qnil;
+    }
+    
+    
+    // adjust for the from and for_length settings to be within the target len
+    unsigned char *scan = target_ptr + from;
+    unsigned char *end = target_ptr + target_len;
+    size_t match_len = 0;
+    size_t match_start = 0;
+    while(scan < end) {
+        if(*scan != source_ptr[sa->suffix_index[sa->starts[*scan]]]) {
+            scan ++;
+        } else {
+            // search remaining stuff for a possible match, which return as a result as well
+            match_len = end - scan;
+            match_start = find_longest_match(source_ptr, source_len, scan, &match_len, 
+                                              sa->starts, sa->ends, sa->suffix_index);
+            
+            if(match_len == 0) {
+                // match not found, which really shouldn't happen
+                break;
+            } else if(match_len > min) {
+                // the match is possibly long enough, drop out
+                break;
+            } else {
+                // the number of possibly matching characters is much too small, so we continue by skipping them
+                scan += match_len;
+                // reset the match_len and match_start to 0 to signal that a match hasn't been found yet
+                match_len = match_start = 0;
+            }
+        } 
+    }
+
+    VALUE result = rb_ary_new();
+    
+    size_t nonmatch_len = (scan - (target_ptr + from));
+    rb_ary_push(result, INT2FIX(nonmatch_len));
+    rb_ary_push(result, INT2FIX(match_start));
+    rb_ary_push(result, INT2FIX(match_len));
+
+    return result;
+}
+
+/*
+ * call-seq:
+ *   sarray.array -> Array  
+ *
+ * Returns a copy of the internal suffix array as an Array of Fixnum objects.  This
+ * array is a copy so you're free to mangle it however you wish.
+ *
+ * A suffix array is the sequence of indices into the source that mark each suffix
+ * as if they were sorted.
+ */
+static VALUE SuffixArray_array(VALUE self) 
+{
+    SuffixArray *sa = NULL;
+    Data_Get_Struct(self, SuffixArray, sa);
+
+    VALUE sa_source = SuffixArray_source(self);
+    
+    if(sa == NULL || sa->suffix_index == NULL || RSTRING(sa_source)->len == 0) {
+        rb_raise(cSAError, ERR_NOT_INITIALIZED);
+    }
+    
+    // get the length of the suffix index
+    size_t source_len = RSTRING(sa_source)->len;
+    size_t i = 0;
+    
+    VALUE result = rb_ary_new();
+    
+    for(i = 0; i < source_len; i++) {
+        rb_ary_push(result, INT2FIX(sa->suffix_index[i]));
+    }
+    
+    return result;
+}
+
+
+/*
+ * call-seq:
+ *     sarray.raw_array -> String
+ * 
+ * Returns the "raw" internal suffix array which is an array of C int types used 
+ * internally as the suffix array.  The purpose of this function is to allow you
+ * to store the suffix_array and then very quickly restore it later without having
+ * to rebuild the suffix array.
+ *
+ * The returned String should be treated as an opaque structure.  It is just a 
+ * copy of the int[] used internally.  This means that it is dependent on your
+ * CPU.  If you want something you can use that is cross platform then use the
+ * SuffixArray.array function instead.
+ */
+static VALUE SuffixArray_raw_array(VALUE self) 
+{
+    SuffixArray *sa = NULL;
+    Data_Get_Struct(self, SuffixArray, sa);
+
+    VALUE sa_source = SuffixArray_source(self);
+    
+    if(sa == NULL || sa->suffix_index == NULL || RSTRING(sa_source)->len == 0) {
+        rb_raise(cSAError, ERR_NOT_INITIALIZED);
+    }
+    
+    // build a string that copies this stuff
+    VALUE result = rb_str_new((const char *)sa->suffix_index, RSTRING(sa_source)->len * sizeof(int));
+
+    return result;
+}
+
+/*
+ * call-seq:
+ *   sarray.start -> Fixnum
+ *
+ * Tells you which index in the suffix array is the longest suffix (also known as the
+ * start of the source string).  If you want to get the beginning of the source string
+ * in a round about way you would do this:
+ *
+ * source = "abracadabra"
+ * sa = SuffixArray.new source
+ * first = source[sa.array[sa.start]]]
+ *
+ * Remember that the start is the index into the suffix array where the source starts,
+ * not an index into the source string (that would just be 0).
+ */
+static VALUE SuffixArray_suffix_start(VALUE self)
+{
+    return rb_iv_get(self, "@suffix_start");
+}
+
+
+
+
+/*
+ * call-seq:
+ *   sarray.all_starts(character) -> Array
+ *
+ * Returns an array containing all the indexes into the source that start
+ * with the given character.  This is a very fast operation since the 
+ * SuffixArray already knows where each character starts and ends in the
+ * suffix array structure internally.  All it does is copy the range of
+ * the suffix array for that region.
+ */
+static VALUE SuffixArray_all_starts(VALUE self, VALUE character)
+{
+    SuffixArray *sa = NULL;
+    Data_Get_Struct(self, SuffixArray, sa);
+    
+    VALUE result = rb_ary_new();
+    VALUE char_str = StringValue(character);
+    
+    // must be at least one length
+    if(RSTRING(char_str)->len > 0) {
+        size_t ch = (size_t)RSTRING(char_str)->ptr[0];
+
+        // go through all the suffix array indices as indicated by sa->starts and sa->ends
+        size_t start = 0;
+    
+        for(start = sa->starts[ch]; start <= sa->ends[ch]; start++) {
+            rb_ary_push(result, INT2FIX(sa->suffix_index[start]));
+        }
+    }
+    
+    return result;
+}
+
+
+static VALUE cSuffixArray;
+
+/**
+ * Implements a SuffixArray structure with functions to do useful operations
+ * quickly such as finding matching and non-matching regions, or finding all
+ * the locations of a given character.  The suffix array construction algorithm
+ * used was written by Sean Quinlan and Sean Doward and is licensed under the 
+ * Plan9 license.  Please refer to the sarray.c file for more information.
+ *
+ * The suffix array construction algorithm used is not the fastest available,
+ * but it was the most correctly implemented.  There is also a lcp.c file 
+ * which implements an O(n) Longest Common Prefix algorithm, but it had
+ * memory errors and buffer overflows which I decided to avoid for now.
+ *
+ * This file is licensed under the GPL license (see LICENSE in the root source
+ * directory).
+ */
+void Init_suffix_array()
+{
+    cSuffixArray = rb_define_class("SuffixArray", rb_cObject);
+    cSAError = rb_define_class("SAError", rb_eStandardError);
+    rb_define_alloc_func(cSuffixArray, SuffixArray_alloc);
+
+    rb_define_method(cSuffixArray, "initialize", SuffixArray_initialize, -1);
+    rb_define_method(cSuffixArray, "longest_match", SuffixArray_longest_match, 2);
+    rb_define_method(cSuffixArray, "longest_nonmatch", SuffixArray_longest_nonmatch, 3);
+    rb_define_method(cSuffixArray, "array", SuffixArray_array, 0);
+    rb_define_method(cSuffixArray, "raw_array", SuffixArray_raw_array, 0);
+    rb_define_method(cSuffixArray, "suffix_start", SuffixArray_suffix_start, 0);
+    rb_define_method(cSuffixArray, "source", SuffixArray_source, 0);
+    rb_define_method(cSuffixArray, "all_starts", SuffixArray_all_starts, 1);
+    
+}