/* Basic functions for @XX@ structures.
 * Copyright (C) 1995, 1996  Free Software Foundation, Inc.
 * 
 * Author: Albin L. Jones <Albin.L.Jones@Dartmouth.EDU>
 * Created: Tue Dec 12 12:33:01 EST 1995
 * Updated: Sat Feb 10 09:08:35 EST 1996
 * Serial: 96.02.10.01
 * 
 * This file is part of the GNU Objective C Class Library.
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 * 
 */ 

/**** Included Headers *******************************************************/

#include <objects/allocs.h>
#include <objects/number.h>
#include <objects/magic.h>
#include <objects/@XX@.h>

/**** Type, Constant, and Macro Definitions **********************************/

#define __@XX@__ 1

/**** Function Implementations ***********************************************/

/** Magic **/

/* Returns XX's magic number. */
int
objects_@XX@_magic (objects_@XX@_t *xx)
{
  return xx->magic;
}

/** Allocs **/

/* Returns the allocs used to create and maintain XX. */
objects_allocs_t
objects_@XX@_allocs (objects_@XX@_t *xx)
{
  return xx->allocs;
}

/** Names **/

/* Returns the name that was given to XX. */
const char *
objects_@XX@_name (objects_@XX@_t *xx)
{
  return xx->name;
}

/* Gives XX a name.  Space is allocated, and the contents of the
 * NUL-terminated NAME are copied.  Deallocating XX frees up the
 * space.  I.e., it is not the responsibility of the programmer to
 * keep track of space allocated for this procedure. */
const char *
objects_@XX@_set_name (objects_@XX@_t *xx, const char *name)
{
  /* Figure out how much space we need. */
  size_t len = strlen (name);
  const char *old_name = xx->name;

  /* Allocate space for the new name.  (Don't forget the extra space
   * for the terminating `NUL'. */
  xx->name = (char *) objects_malloc (xx->allocs, len + 1);

  /* If the allocation was successful, copy the new name over and get
   * rid of the old name. */
  if (xx->name != NULL)
    {
      /* Copy over the new name. */
      strncpy (xx->name, name, len);

      /* Free up any space we set aside for any older name. */
      if (old_name != NULL)
	objects_free (xx->allocs, old_name);
    }

  return xx->name;
}

/* Takes away XX's name. */
void
objects_@XX@_unset_name (objects_@XX@_t *xx)
{
  /* Free it. */
  if (xx->name != NULL)
    objects_free (xx->allocs, xx->name);

  /* Reset it. */
  xx->name = NULL;

  return;
}

/** Number **/

/* Returns the (process-wide) unique number given to the Libobjects
 * structure XX.  See <objects/number.h> for more info. */
size_t
objects_@XX@_number (objects_@XX@_t *xx)
{
  return xx->number;
}

/* Gives XX a new (process-wide) unique number.  Numbers are not
 * reused.  See <objects/number.h> for more info. */
size_t
_objects_@XX@_set_serial_number (objects_@XX@_t *xx)
{
  size_t old_number;

  old_number = xx->number;
  xx->number = (___objects_number_serial)++;

  return old_number;
}

/** Extras **/

/* Sets the callbacks associated with XX's ``extra''.  NOTE: This must
 * be done before calling `objects_@XX@_set_extra()', as these callbacks
 * are used in that routine. */
objects_callbacks_t
objects_@XX@_set_extra_callbacks (objects_@XX@_t *xx, objects_callbacks_t callbacks)
{
  objects_callbacks_t old_callbacks;

  /* Remember the old callbacks for later. */
  old_callbacks = xx->extra_callbacks;

  /* Set the new callbacks. */
  xx->extra_callbacks = callbacks;

  /* Release the old contents. */
  objects_release (old_callbacks, (void*)xx->extra, xx);

  /* Set the contents to something noticible. */
  xx->extra = (xx->extra_callbacks).not_an_item_marker;

  return old_callbacks;
}

/* Returns the callbacks associated with XX's ``extra''. */
objects_callbacks_t
objects_@XX@_extra_callbacks (objects_@XX@_t *xx, objects_callbacks_t callbacks)
{
  return xx->extra_callbacks;
}

/* Returns XX's ``extra'', a little extra space that each Libobjects
 * structure carries around with it.  Its use is
 * implementation-dependent. */
const void *
objects_@XX@_extra (objects_@XX@_t *xx)
{
  return xx->extra;
}

/* Sets XX's ``extra'', a little extra space that each Libobjects structure
 * carries around with it.  Its use is implementation-dependent. */
const void *
objects_@XX@_set_extra (objects_@XX@_t *xx, const void *extra)
{
  const void *old_extra;

  /* Out with the old, and in with the new. */
  old_extra = xx->extra;
  xx->extra = objects_retain (xx->extra_callbacks, extra, xx);
  objects_release (xx->extra_callbacks, (void*)old_extra, xx);

  return old_extra;
}

/* Resets XX's ``extra''. */
void
objects_@XX@_unset_extra (objects_@XX@_t *xx)
{
  /* Release XX's extra. */
  objects_release (xx->extra_callbacks, (void*)xx->extra, xx);

  /* Reset XX's extra. */
  xx->extra = (xx->extra_callbacks).not_an_item_marker;

  return;
}

/** Low-level Creation and Destruction **/

/* Handles the universal, low-level allocation of Libobjects structures. */
objects_@XX@_t *
_objects_@XX@_alloc_with_allocs (objects_allocs_t allocs)
{
  objects_@XX@_t *xx;

  /* Try to allocate some space for XX. */
  xx = objects_malloc (allocs, sizeof (objects_@XX@_t));

  /* The `objects_malloc()' was successful. */
  if (xx != NULL)
    {
      _objects_@XX@_set_serial_number (xx);
      xx->magic = _OBJECTS_MAGIC_@XX@;
      xx->name = NULL;
      xx->allocs = allocs;
      xx->extra_callbacks = objects_callbacks_for_void_p;
      xx->extra = 0;

      /* Increment the counter of allocated Libobjects structures. */
      ++(___objects_number_allocated);
    }

  return xx;
}

/* Handles the universal, low-level deallocation of Libobjects structures. */
void
_objects_@XX@_dealloc (objects_@XX@_t *xx)
{
  /* Make sure XX is valid. */
  if (xx != NULL)
    {
      /* Free up any space we needed to keep track of XX's name. */
      if (xx->name != NULL)
	objects_free (objects_@XX@_allocs (xx), xx->name);

      /* Release XX's extra. */
      objects_@XX@_unset_extra (xx);

      /* Free up XX itself. */
      objects_free (objects_@XX@_allocs (xx), xx);

      /* Increment the counter of deallocated Libobjects structures. */
      ++(___objects_number_deallocated);
    }

  return;
}

/* Handles the low-level copying of Libobjects structures. */
objects_@XX@_t *
_objects_@XX@_copy_with_allocs (objects_@XX@_t *xx, objects_allocs_t allocs)
{
  objects_@XX@_t *new;

  /* Create a new structure. */
  new = _objects_@XX@_alloc_with_allocs (allocs);

  if (new != NULL)
    {
      /* Copy over XX's name. */
      objects_@XX@_set_name (new, objects_@XX@_name (xx));

      /* Copy over XX's extras. */
      objects_@XX@_set_extra_callbacks (new, xx->extra_callbacks);
      objects_@XX@_set_extra (new, xx->extra);
    }

  return new;
}