ffstring.h

Go to the documentation of this file.

/*
 * finflect - Algorithms and tools for inflecting Finnish nouns
 * Copyright (C) 2004, 2005  The FinFlect Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *
 * For the complete legal text of the GNU Lesser General Public License,
 * see the file LICENSE. For a complete list of authors and copyright
 * holders, see the file AUTHORS.
 */

/**
 * @file ffstring.h
 * Defines a string datatype and related operations (implemented in ffstring.c) designed
 * for maximum flexibility for the programmer.
 * A general rule for argument order: If we're creating a new ffstring, the source
 * comes before the target. If we're just operating on an existing one, the target comes
 * first.
 */


#ifndef __FFSTRING_H
#define __FFSTRING_H

#ifdef __cplusplus
extern "C" {
#endif

#include "fftypes.h"

/**
 * Our much beloved string data type.
 */
typedef struct ffstring
{
  /**
   * Length of the string
   */
  ffuint32 len;
  /**
   * Data
   */
  ffchar* str;
}
ffstring;

/**
 * Creates a new ffstring from a C-style string.
 * @param source The default content for the new ffstring. Must be a valid C-style string.
 * @param target Pointer to an uninitialized ffstring.
 * @return 0 on success. -1 on memory error.
 */
ffint32 ffstring_create(const ffchar* source, ffstring* target);


/**
 * Deletes an ffstring.
 * @param target The ffstring to be deleted.
 * @return 0 on success.
 */
ffint32 ffstring_delete(ffstring* target);


/**
 * Creates a copy of an ffstring. The caller should take care of disposing of it.
 * @param source String to be copied
 * @param target Pointer to uninitialized ffstring.
 * @return 0 on success or the error number returned by ffstring_create.
 */
ffint32 ffstring_copy(const ffstring* source, ffstring* target);

/**
 * Deletes count characters from the end of the target string. count must smaller or
 * equal to current length or an error is returned. 
 * The original data remains unchanged if an error occures.
 * (DFE == Delete From End)
 * @param target String from where characters are deleted
 * @param count How many characters are deleted
 * @return 0 on success. -1 on memory error. -2 on argument error.
 */
ffint32 ffstring_dfe(ffstring* target, ffuint32 count);

/**
 * Replaces the last count characters from the end of the target string with the C-style
 * string append. (RFE == Replace From End)
 * @param target String to modify
 * @param count Number of characters to delete
 * @param append String to append
 * @return 0 on success. -1 on memory error. -2 on argument error.
 */
ffint32 ffstring_rfe(ffstring* target, ffuint32 count, ffchar* append);

/**
 * Replaces the last count characters from the end of the target string with the ffstring
 * append. (RFE == Replace From End)
 * @param target The ffstring to modify
 * @param count Number of characters to delete
 * @param append The ffstring to append
 * @return 0 on success. -1 on memory error. -2 on argument error.
 */
ffint32 ffstring_rfe_ff(ffstring* target, ffuint32 count, const ffstring* append);

/**
 * Append a C-style string to the target ffstring. If the process fails, the target
 * ffstring remains unchanged.
 * @param target The target ffstring
 * @param append The C-style string to be appended
 * @return 0 on success. -1 on memory error.
 */
ffint32 ffstring_append(ffstring* target, ffchar* append);

/**
 * Append a ffstring to the target ffstring.
 * @param target The target ffstring
 * @param append The ffstring to be appended
 * @return 0 on success. -1 on memory error.
 */
ffint32 ffstring_append_ff(ffstring* target, const ffstring* append);
 
/**
 * Returns the current number of ffstring instances.
 * @return The current number of ffstring instances.
 */
ffint32 ffstring_instcount(void);

/**
 * Creates a new ffstring from at most count characters (not including the terminating
 * null byte) from the head of the source ffstring. The caller should
 * take care of disposing of the new ffstring.
 * @param source The source ffstring
 * @param count The number of characters to extract
 * @param target The target ffstring
 * @return 0 on success, -1 on memory error, -2 on argument terror
 */
ffint32 ffstring_tail(const ffstring* source, ffint32 count, ffstring* target);

/**
 * Converts a ffstring to lowercase.
 * @param target The ffstring to convert.
 * @return 0 on success, -1 on error.
 */
ffint32 ffstring_tolower(ffstring* target);

/**
 * Creates a lowercase copy of an ffstring. The caller has to take care of disposing of the new
 * ffstring.
 * @param source The source ffstring
 * @param target The uninitialized target ffstring
 * @return 0 on success, -1 on memory error
 */
ffint32 ffstring_lower(const ffstring* source, ffstring* target);

/**
 * Case-sensitively compares an ffstring to a C-style string using strcmp(3).
 * @param left The first string
 * @param right The second string
 * @return below zero if left < right, 0 if left == right, above zero if left > right
 */
ffint32 ffstring_compare(const ffstring* left, const ffchar* right);

/**
 * Case-insensitively compares an ffstring to a C-style string using tolower(3) and strcmp(3).
 * @param left The first string
 * @param right The second string
 * @return below zero if left < right, 0 if left == right, above zero if left > right
 */
ffint32 ffstring_compare_ci(const ffstring* left, const ffchar* right);

/**
 * Case-sensitively compares an ffstring to another using strcmp(3).
 * @param left The first string
 * @param right The second string
 * @return below zero if left < right, 0 if left == right, above zero if left > right
 */
ffint32 ffstring_compare_ff(const ffstring* left, const ffstring* right);

/**
 * Case-insensitively compares an ffstring to another string using tolower(3) and strcmp(3).
 * @param left The first string
 * @param right The second string
 * @return below zero if left < right, 0 if left == right, above zero if left > right
 */
ffint32 ffstring_compare_ff_ci(const ffstring* left, const ffstring* right);

/**
 * Case-sensitively compares the specified number of last characters of the given ffstring
 * to a C-style string.
 * @param left The string whose tail we're going to compare
 * @param count The number of characters to compare
 * @param right The C-style string to compare to
 * @return below zero if the extracted tail < right, 0 if they're the same, above zero otherwise
 */
ffint32 ffstring_compare_tail(const ffstring* left, ffuint32 count, const ffchar* right);

/**
 * Case-insensitively compares the specified number of last characters of the given ffstring
 * to a C-style string.
 * @param left The string whose tail we're going to compare
 * @param count The number of characters to compare
 * @param right The C-style string to compare to
 * @return below zero if the extracted tail < right, 0 if they're the same, above zero otherwise
 */
ffint32 ffstring_compare_tail_ci(const ffstring* left, ffuint32 count, const ffchar* right);

/**
 * Case-sensitively compares the specified number of last characters of the given ffstring
 * to another ffstring.
 * @param left The string whose tail we're going to compare
 * @param count The number of characters to compare
 * @param right The ffstring to compare to
 * @return below zero if the extracted tail < right, 0 if they're the same, above zero otherwise
 */
ffint32 ffstring_compare_tail_ff(const ffstring* left, ffuint32 count, const ffstring* right);

/**
 * Case-insensitively compares the specified number of last characters of the given ffstring
 * to another ffstring.
 * @param left The string whose tail we're going to compare
 * @param count The number of characters to compare
 * @param right The ffstring to compare to
 * @return below zero if the extracted tail < right, 0 if they're the same, above zero otherwise
 */
ffint32 ffstring_compare_tail_ff_ci(const ffstring* left, ffuint32 count, const ffstring* right);

/**
 * Returns the last character of the given ffstring.
 * @param source The source ffstring
 * @return The last character
 * @todo Wrong description
 */
ffchar ffstring_last(const ffstring* source);

/**
 * Case-sensitively compares the last character of the given ffstring to a given character
 * @param left The ffstring whose last character we're going to compare
 * @param right The character to compare to
 * @return below zero if last(left) < right, zero if last(left) == right, above zero otherwise
 */
ffint32 ffstring_compare_last(const ffstring* left, const ffchar right);

/**
 * Case-insensitively compares the last character of the given ffstring to a given character
 * @param left The ffstring whose last character we're going to compare
 * @param right The character to compare to
 * @return below zero if last(left) < right, zero if last(left) == right, above zero otherwise
 */
ffint32 ffstring_compare_last_ci(const ffstring* left, const ffchar right);

/**
 * Checks if the given ffstring and C-style string are the same.
 * @param left The first string
 * @param right The second string
 * @return 1 if the strings are the same; 0 if they're not.
 */
ffbool ffstring_equals(const ffstring* left, const ffchar* right);

/**
 * Case-insensitively checks if the given ffstring and C-style string are the same.
 * @param left The first string
 * @param right The second string
 * @return 1 if the strings are the same; 0 if they're not.
 */
ffbool ffstring_equals_ci(const ffstring* left, const ffchar* right);

/**
 * Checks if the two given ffstrings are the same.
 * @param left The first string
 * @param right The second string
 * @return 1 if the strings are the same; 0 if they're not.
 */
ffbool ffstring_equals_ff(const ffstring* left, const ffstring* right);

/**
 * Case-insensitively checks if the two given ffstrings are the same.
 * @param left The first string
 * @param right The second string
 * @return 1 if the strings are the same; 0 if they're not.
 */
ffbool ffstring_equals_ff_ci(const ffstring* left, const ffstring* right);

/**
 * Checks if the tail of the given ffstring is the same as the given C-style string.
 * @param left The string whose tail we are going to compare
 * @param count The length of the tail to be compared
 * @param right The string we're comparing to
 */
ffbool ffstring_tail_equals(const ffstring* left, const ffint32 count, const ffchar* right);

/**
 * Case-insensitively checks if the tail of the given ffstring is the same as the given C-style string.
 * @param left The string whose tail we are going to compare
 * @param count The length of the tail to be compared
 * @param right The string we're comparing to
 */
ffbool ffstring_tail_equals_ci(const ffstring* left, const ffint32 count, const ffchar* right);

/**
 * Checks if the tail of the given ffstring equals the other given ffstring.
 * @param left The string whose tail we are going to compare
 * @param count The length of the tail to be compared
 * @param right The string we're comparing to
 */
ffbool ffstring_tail_equals_ff(const ffstring* left, const ffint32 count, const ffstring* right);

/**
 * Case-insensitively checks if the tail of the given ffstring equals the other given ffstring.
 * @param left The string whose tail we are going to compare
 * @param count The length of the tail to be compared
 * @param right The string we're comparing to
 */
ffbool ffstring_tail_equals_ff_ci(const ffstring* left, const ffint32 count, const ffstring* right);

/**
 * Checks if the last character of the given string matches the given character.
 * @param left The string whose last character we are going to compare
 * @param right The character to compare to
 */    
ffbool ffstring_last_equals(const ffstring* left, ffchar right);

/**
 * Case-insensitively checks if the last character of the given string matches the given character.
 * @param left The string whose last character we are going to compare
 * @param right The character to compare to
 */  
ffbool ffstring_last_equals_ci(const ffstring* left, ffchar right);

/**
 * Decreases the ffstring instance counter. This function is meant to be used when an ffstring
 * struct ceases to exist but the real string data (ffstring.str) remains. USE WITH CAUTION!
 * @return 0 on success, -1 if the instance counter would go negative if decreased
 */
ffint32 ffstring_decinst(void);

#ifdef __cplusplus
}
#endif

#endif

---