segment.h

/*
 * Copyright 2003, 2004 Ian Searle. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following
 * conditions are met:  
 *
 * 1: Redistributions of source code must retain the above
 * copyright notice, this list of conditions and the following
 * disclaimer. 
 *
 * 2: Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following
 * disclaimer in the documentation and/or other materials
 * provided with the distribution. 
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY  EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL IAN SEARLE OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
 * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE. 
 *
 */

/*
 * segment.h
 * Definition of Segment library. 
 *
 * Introduction:  The segment library is not much all by itself.  It
 *                is merely a container object that holds reference to
 *                a character array.  It does not, and cannot have much
 *                intelligence.  Since we want different Views to have
 *                different representations of the same Segments, we
 *                have to put the smarts for those operations in the View.
 *
 * Notes:
 *
 * 1: Since multiple Views can reference the same Segments, we use
 *    reference counts to control the life-cycle of each Segment.
 *    All segments are created with a reference count of 1.  Every
 *    time segmentDelete() is called, the reference count is
 *    decremented.  Once the reference count reaches zero, the Segment
 *    is really deleted.
 *
 * 2: Segments contain string data that may (probably will) contain
 *    NULL characters.  Thus, we cannot use normal C-language string
 *    operations on them as they will fail in the presence of NULL
 *    characters embedded in the character array.
 *
 */

#ifndef _SEGMENT_H
#define _SEGMENT_H

#include <stdlib.h>

typedef struct _segment Segment;

struct _segment {
  char *data;              
  unsigned int ref_count;  
  unsigned int len;        
};

/*
 * Initialize the segment memory allocation routines. 
 * The defaults are the system malloc and free.  If those
 * are acceptable, use of this function is not necessary.
 */
void segment_Init(void *(*seg_allocate)(size_t), void (*seg_deallocate)(void *));

/*
 * Create a Segment with a borrowed reference to the data.
 */
Segment *segment_CreateBorrowed(char *str, unsigned int len);

/*
 * Create a Segment with a owned reference to the data.
 */
Segment *segment_CreateOwned(char *str, unsigned int len);

/*
 * Delete a Segment (with borrowed data).
 * Returns: > 0 if there is an error.
 *            0 on sucess.
 */
void segment_DeleteBorrowed(Segment *seg);

/*
 * Delete a Segment (with owned data).
 * Returns: > 0 if there is an error.
 *            0 on sucess.
 */
void segment_DeleteOwned(Segment *seg);

Segment *segment_Copy(Segment *seg);

/*
 * Return a character from a segment.
 * The character is returned through a character pointer.
 */
unsigned int segment_GetChar(Segment *seg, unsigned int pos, char *retval);

/*
 * Return a pointer to the segment's data.
 */
char *segment_DataPtr(Segment *seg, unsigned int index);

/*
 * Print a Segment to stdout.
 * Primarily for debugging.
 */
void segment_Print(Segment *seg);

/*
 * Print just part of a segment to stdout.
 */
unsigned int segment_PrintPiece(Segment *seg, unsigned int start, unsigned int end);

#endif  /* _SEGMENT_H */

---