source: trunk/foundation/idl/nomstring.idl@ 225

/* ***** BEGIN LICENSE BLOCK *****
* Version: CDDL 1.0/LGPL 2.1
*
* The contents of this file are subject to the COMMON DEVELOPMENT AND
* DISTRIBUTION LICENSE (CDDL) Version 1.0 (the "License"); you may not use
* this file except in compliance with the License. You may obtain a copy of
* the License at http://www.sun.com/cddl/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is "NOM" Netlabs Object Model
*
* The Initial Developer of the Original Code is
* netlabs.org: Chris Wohlgemuth <cinc-ml@netlabs.org>.
* Portions created by the Initial Developer are Copyright (C) 2005-2006
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
* case the provisions of the LGPL are applicable instead of those above. If
* you wish to allow use of your version of this file only under the terms of
* the LGPL, and not to allow others to use your version of this file under
* the terms of the CDDL, indicate your decision by deleting the provisions
* above and replace them with the notice and other provisions required by the
* LGPL. If you do not delete the provisions above, a recipient may use your
* version of this file under the terms of any one of the CDDL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */

#ifndef NOMSTRING_IDL_INCLUDED
#define NOMSTRING_IDL_INCLUDED

#include "nomobj.idl"
#include "nomfoundation.idl"

NOMCLASSNAME(NOMString);

/** \class NOMString
    The NOMString class is used for strings which automatically grow or shrink.
    Methods are provided for common tasks when dealing with strings like inserting or
    appending strings. A string object never can be empty. It always is a string which may have a length of zero.
    These methods are threadsafe by always working with copies.

    Note that you don't have to delete a NOMString object. This is done by the garbage collector. Deleting
    it doesn't hurt, though.
 */
interface NOMString : NOMObject
{
  /**
     The current version of this class is 1.0
   */
  NOMCLASSVERSION(1, 0);

  /**
     Assign a string to this NOMString. An initially created NOMString object is empty.
     This method can be used to assign some value to it.

     \remark
     This method does not work on a copy. So by assigning a value to the NOMString the
     old contents is lost. This may have sideeffects in multithreaded environments if used without care.

     \sa assignCString()
   */
  PNOMString assign(in PNOMString nomString);   

  /**
     Assign a C string to this NOMString. An initially created NOMString object is empty.
     This method can be used to assign some value to it.

     \remark
     This method does not work on a copy. So by assigning a value to the NOMString the old contents
     is lost. This may have sideeffects in multithreaded environments if used without care.

     \sa assign()
  */
  PNOMString assignCString(in string chrString);   

  /**
     Returns the C string holding the info inside the string object. Use with care. 
     In most cases you rather want to use copyCString() instead.

     \return The C string representing the contents of the string object.

     \sa copyCString()
  */
  string queryCString();

  /**
     Add the NOMString nomString to the end of the string object. 

     \param nomString A NOMString object to be put at the end of the string.
     \return     
     The returned NOMString object is a new object which is owned by the caller.

     \sa appendCString(), prepend()
   */
  PNOMString append(in PNOMString nomString);

  /**
     Prepend the NOMString \e nomString to the given string object and return a pointer to a
     new string object.

     \param nomString A NOMString object to be put in front of the string.
     \return
     The returned NOMString object is a new object which is owned by the caller.

     \sa prependCString()
   */   
  PNOMString prepend(in PNOMString nomString);

  /**
     Append the given C string to the end of the string held by the NOMString object.

     \param chrString A null terminated string.
     \return
     The NOMString object is a new object which is owned by the caller.

     \sa append(), prependCString()
   */
  PNOMString appendCString(in string chrString);

  /**
     Prepend the C string to the string object.

     \param chrString A null terminated string.
     \return
     The NOMString object is a new object which is owned by the caller.

     \sa appendCString(), prepend()
   */
  PNOMString prependCString(in string chrString);

  /**
     \return Returns the length of the string in characters.
   */
  unsigned long length();

  /**
     Cuts off the end of a string leaving the first ulNewLen characters.

     \return
     The returned NOMString object is a new object holding the truncated string
     which is owned by the caller. 
  */
  PNOMString truncate(in unsigned long ulNewLen);

  /**
     Create a copy of the NOMString object this method is called on. The caller
     owns the new NOMString object.

     \return A new NOMString object

     \sa copyCString()
  */
  PNOMString copy();

  /**
     Returns a copy of the C string holding the info inside the string object.

     \return
     The returned C string is owned by the caller.

     \sa copy()
   */
  string copyCString();

  /**
     Override of nomInit() to initialize the GString */
  NOMOVERRIDE(nomInit);

  /**
     The GString holding the data
  */
  NOMINSTANCEVAR(PGString gString);
};

#endif  /* NOMSTRING_IDL_INCLUDED */