string.h

Go to the documentation of this file.

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.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.apache.org/licenses/LICENSE-2.0 .
 */

/*
 * This file is part of LibreOffice published API.
 */

#ifndef INCLUDED_RTL_STRING_H
#define INCLUDED_RTL_STRING_H

#include "sal/config.h"

#include "osl/interlck.h"
#include "rtl/textcvt.h"
#include "sal/saldllapi.h"
#include "sal/types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ======================================================================= */

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_getLength(
        const char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compare(
        const char * first, const char * second ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compare_WithLength(
        const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_shortenedCompare_WithLength(
        const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_reverseCompare_WithLength(
        const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase(
        const char * first, const char * second ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase_WithLength(
        const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_shortenedCompareIgnoreAsciiCase_WithLength(
        const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_hashCode(
        const char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_hashCode_WithLength(
        const char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfChar(
        const char * str, char ch ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfChar_WithLength(
        const char * str, sal_Int32 len, char ch ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfChar(
        const char * str, char ch ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfChar_WithLength(
        const char * str, sal_Int32 len, char ch ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfStr(
        const char * str, const char * subStr ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfStr_WithLength(
        const char * str, sal_Int32 len, const char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfStr(
        const char * str, const char * subStr ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfStr_WithLength(
        const char * str, sal_Int32 len, const char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_str_replaceChar(
        char * str, char oldChar, char newChar ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_str_replaceChar_WithLength(
        char * str, sal_Int32 len, char oldChar, char newChar ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiLowerCase(
        char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiLowerCase_WithLength(
        char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiUpperCase(
        char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiUpperCase_WithLength(
        char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_trim(
        char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_trim_WithLength(
        char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfBoolean(
        char * str, sal_Bool b ) SAL_THROW_EXTERN_C();
#define RTL_STR_MAX_VALUEOFBOOLEAN 6

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfChar(
        char * str, char ch ) SAL_THROW_EXTERN_C();
#define RTL_STR_MAX_VALUEOFCHAR 2

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfInt32(
        char * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
#define RTL_STR_MIN_RADIX           2
#define RTL_STR_MAX_RADIX           36
#define RTL_STR_MAX_VALUEOFINT32    33

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfInt64(
        char * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
#define RTL_STR_MAX_VALUEOFINT64 65

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfUInt64(
        char * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
#define RTL_STR_MAX_VALUEOFUINT64 65

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfFloat(
        char * str, float f ) SAL_THROW_EXTERN_C();
#define RTL_STR_MAX_VALUEOFFLOAT 15

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfDouble(
        char * str, double d ) SAL_THROW_EXTERN_C();
#define RTL_STR_MAX_VALUEOFDOUBLE 25

SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_str_toBoolean(
        const char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_toInt32(
        const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_str_toUInt32(
        const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_str_toInt64(
        const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_str_toInt64_WithLength(
        const char * str, sal_Int16 radix, sal_Int32 nStrLength ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_str_toUInt64(
        const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC float SAL_CALL rtl_str_toFloat(
        const char * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC double SAL_CALL rtl_str_toDouble(
        const char * str ) SAL_THROW_EXTERN_C();

/* ======================================================================= */

typedef struct _rtl_String
{
    oslInterlockedCount refCount; /* opaque */
    sal_Int32           length;
    char            buffer[1];
} rtl_String;
/* ----------------------------------------------------------------------- */

SAL_DLLPUBLIC void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC rtl_String * SAL_CALL rtl_string_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const char * value ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const char * value, sal_Int32 len ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromSubString(
        rtl_String ** newStr, const rtl_String * from,
        sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromLiteral( rtl_String ** newStr, const char * value, sal_Int32 len, sal_Int32 allocExtra ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt(
        rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C();

#ifdef LIBO_INTERNAL_ONLY
SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt_WithLength (
        rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, char const * subStr, sal_Int32 substrLen ) SAL_THROW_EXTERN_C();
#endif

SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplace(
        rtl_String ** newStr, rtl_String * str, char oldChar, char newChar ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceFirst(
    rtl_String ** newStr, rtl_String * str, char const * from,
    sal_Int32 fromLength, char const * to, sal_Int32 toLength,
    sal_Int32 * index) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceAll(
    rtl_String ** newStr, rtl_String * str, char const * from,
    sal_Int32 fromLength, char const * to, sal_Int32 toLength)
    SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiLowerCase(
        rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiUpperCase(
        rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_newTrim(
        rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getToken(
        rtl_String ** newStr , rtl_String * str, sal_Int32 token, char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();

/* ======================================================================= */

// The &foo[0] trick is intentional, it makes sure the type is char* or const char*
// (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed).
// This is to avoid mistaken use with functions that accept string literals
// (i.e. const char (&)[N]) where usage of this macro otherwise could match
// the argument and a following int argument with a default value (e.g. OString::match()).
#define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \
    ((sal_Int32)SAL_N_ELEMENTS(constAsciiStr)-1)

#define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1))

/* ======================================================================= */

/* predefined constants for String-Conversion */
#define OUSTRING_TO_OSTRING_CVTFLAGS    (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\
                                         RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\
                                         RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\
                                         RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0)

/* ----------------------------------------------------------------------- */

SAL_DLLPUBLIC void SAL_CALL rtl_uString2String(
        rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertUStringToString(
                                             rtl_String ** pTarget,
                                             sal_Unicode const * pSource,
                                             sal_Int32 nLength,
                                             rtl_TextEncoding nEncoding,
                                             sal_uInt32 nFlags)
    SAL_THROW_EXTERN_C();

SAL_DLLPUBLIC void SAL_CALL rtl_string_ensureCapacity( rtl_String ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();

#ifdef __cplusplus
}
#endif

#endif // INCLUDED_RTL_STRING_H

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */