ext/str.h

   1 // Copyright 2008-2009 Wincent Colaiuta. All rights reserved.
   2 //
   3 // Redistribution and use in source and binary forms, with or without
   4 // modification, are permitted provided that the following conditions are met:
   5 //
   6 // 1. Redistributions of source code must retain the above copyright notice,
   7 //    this list of conditions and the following disclaimer.
   8 // 2. Redistributions in binary form must reproduce the above copyright notice,
   9 //    this list of conditions and the following disclaimer in the documentation
  10 //    and/or other materials provided with the distribution.
  11 //
  12 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  13 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
  16 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  17 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  18 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  19 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  20 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  21 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  22 // POSSIBILITY OF SUCH DAMAGE.
  23
  24 #include "ruby_compat.h"
  25
  26 typedef struct
  27 {
  28     char *ptr;
  29     long len;
  30     long capacity;
  31 } str_t;
  32
  33 // Mark the str struct designated by ptr as a participant in Ruby's mark-and-sweep garbage collection scheme.
  34 // A variable named name is placed on the C stack to prevent the structure from being prematurely collected.
  35 #define GC_WRAP_STR(ptr, name) volatile VALUE name __attribute__((unused)) = Data_Wrap_Struct(rb_cObject, 0, str_free, ptr)
  36
  37 // create a new, empty string struct
  38 str_t *str_new(void);
  39
  40 // create a new, empty string struct with capacity len
  41 str_t *str_new_size(long len);
  42
  43 // create a new string struct and initialize it with a copy of the buffer of length len pointed to by src
  44 str_t *str_new_copy(char *src, long len);
  45
  46 // create a new string struct and initialize it with the buffer of length len pointed to by src
  47 // no copy is made; the struct takes ownership of the buffer and will free it when the struct is disposed of
  48 str_t *str_new_no_copy(char *src, long len);
  49
  50 // convenience method for testing
  51 str_t *str_new_from_string(VALUE string);
  52
  53 // convenience method for testing
  54 VALUE string_from_str(str_t *str);
  55
  56 // grows a string's capacity to the specified length
  57 void str_grow(str_t *str, long len);
  58
  59 void str_append(str_t *str, char *src, long len);
  60
  61 // appends the "other" string struct onto str
  62 void str_append_str(str_t *str, str_t *other);
  63
  64 // this is a temporary convenience measure
  65 // later on if I develop in-place variants of some functions this won't be needed
  66 void str_swap(str_t **a, str_t **b);
  67
  68 // don't actually free the memory yet
  69 // this makes str structs very useful when reusing buffers because it avoids reallocation
  70 void str_clear(str_t *str);
  71
  72 void str_free(str_t *str);