// Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
**********************************************************************
* Copyright (C) 2005-2013, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
* file name: ucsdet.h
* encoding: US-ASCII
* indentation:4
*
* created on: 2005Aug04
* created by: Andy Heninger
*
* ICU Character Set Detection, API for C
*
* Draft version 18 Oct 2005
*
*/
#ifndef __UCSDET_H
#define __UCSDET_H
#include "unicode/utypes.h"
#if !UCONFIG_NO_CONVERSION
#include "unicode/localpointer.h"
#include "unicode/uenum.h"
/**
* \file
* \brief C API: Charset Detection API
*
* This API provides a facility for detecting the
* charset or encoding of character data in an unknown text format.
* The input data can be from an array of bytes.
* <p>
* Character set detection is at best an imprecise operation. The detection
* process will attempt to identify the charset that best matches the characteristics
* of the byte data, but the process is partly statistical in nature, and
* the results can not be guaranteed to always be correct.
* <p>
* For best accuracy in charset detection, the input data should be primarily
* in a single language, and a minimum of a few hundred bytes worth of plain text
* in the language are needed. The detection process will attempt to
* ignore html or xml style markup that could otherwise obscure the content.
*/
struct UCharsetDetector;
/**
* Structure representing a charset detector
* @stable ICU 3.6
*/
typedef struct UCharsetDetector UCharsetDetector;
struct UCharsetMatch;
/**
* Opaque structure representing a match that was identified
* from a charset detection operation.
* @stable ICU 3.6
*/
typedef struct UCharsetMatch UCharsetMatch;
/**
* Open a charset detector.
*
* @param status Any error conditions occurring during the open
* operation are reported back in this variable.
* @return the newly opened charset detector.
* @stable ICU 3.6
*/
U_STABLE UCharsetDetector * U_EXPORT2
ucsdet_open(UErrorCode *status);
/**
* Close a charset detector. All storage and any other resources
* owned by this charset detector will be released. Failure to
* close a charset detector when finished with it can result in
* memory leaks in the application.
*
* @param ucsd The charset detector to be closed.
* @stable ICU 3.6
*/
U_STABLE void U_EXPORT2
ucsdet_close(UCharsetDetector *ucsd);
#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
/**
* \class LocalUCharsetDetectorPointer
* "Smart pointer" class, closes a UCharsetDetector via ucsdet_close().
* For most methods see the LocalPointerBase base class.
*
* @see LocalPointerBase
* @see LocalPointer
* @stable ICU 4.4
*/
U_DEFINE_LOCAL_OPEN_POINTER(LocalUCharsetDetectorPointer, UCharsetDetector, ucsdet_close);
U_NAMESPACE_END
#endif
/**
* Set the input byte data whose charset is to detected.
*
* Ownership of the input text byte array remains with the caller.
* The input string must not be altered or deleted until the charset
* detector is either closed or reset to refer to different input text.
*
* @param ucsd the charset detector to be used.
* @param textIn the input text of unknown encoding. .
* @param len the length of the input text, or -1 if the text
* is NUL terminated.
* @param status any error conditions are reported back in this variable.
*
* @stable ICU 3.6
*/
U_STABLE void U_EXPORT2
ucsdet_setText(UCharsetDetector *ucsd, const char *textIn, int32_t len, UErrorCode *status);
/** Set the declared encoding for charset detection.
* The declared encoding of an input text is an encoding obtained
* by the user from an http header or xml declaration or similar source that
* can be provided as an additional hint to the charset detector.
*
* How and whether the declared encoding will be used during the
* detection process is TBD.
*
* @param ucsd the charset detector to be used.
* @param encoding an encoding for the current data obtained from
* a header or declaration or other source outside
* of the byte data itself.
* @param length the length of the encoding name, or -1 if the name string
* is NUL terminated.
* @param status any error conditions are reported back in this variable.
*
* @stable ICU 3.6
*/
U_STABLE void U_EXPORT2
ucsdet_setDeclaredEncoding(UCharsetDetector *ucsd, const char *encoding, int32_t length, UErrorCode *status);
/**
* Return the charset that best matches the supplied input data.
*
* Note though, that because the detection
* only looks at the start of the input data,
* there is a possibility that the returned charset will fail to handle
* the full set of input data.
* <p>
* The returned UCharsetMatch object is owned by the UCharsetDetector.
* It will remain valid until the detector input is reset, or until
* the detector is closed.
* <p>
* The function will fail if
* <ul>
* <li>no charset appears to match the data.</li>
* <li>no input text has been provided</li>
* </ul>
*
* @param ucsd the charset detector to be used.
* @param status any error conditions are reported back in this variable.
* @return a UCharsetMatch representing the best matching charset,
* or NULL if no charset matches the byte data.
*
* @stable ICU 3.6
*/
U_STABLE const UCharsetMatch * U_EXPORT2
ucsdet_detect(UCharsetDetector *ucsd, UErrorCode *status);
/**
* Find all charset matches that appear to be consistent with the input,
* returning an array of results. The results are ordered with the
* best quality match first.
*
* Because the detection only looks at a limited amount of the
* input byte data, some of the returned charsets may fail to handle
* the all of input data.
* <p>
* The returned UCharsetMatch objects are owned by the UCharsetDetector.
* They will remain valid until the detector is closed or modified
*
* <p>
* Return an error if
* <ul>
* <li>no charsets appear to match the input data.</li>
* <li>no input text has been provided</li>
* </ul>
*
* @param ucsd the charset detector to be used.
* @param matchesFound pointer to a variable that will be set to the
* number of charsets identified that are consistent with
* the input data. Output only.
* @param status any error conditions are reported back in this variable.
* @return A pointer to an array of pointers to UCharSetMatch objects.
* This array, and the UCharSetMatch instances to which it refers,
* are owned by the UCharsetDetector, and will remain valid until
* the detector is closed or modified.
* @stable ICU 3.6
*/
U_STABLE const UCharsetMatch ** U_EXPORT2
ucsdet_detectAll(UCharsetDetector *ucsd, int32_t *matchesFound, UErrorCode *status);
/**
* Get the name of the charset represented by a UCharsetMatch.
*
* The storage for the returned name string is owned by the
* UCharsetMatch, and will remain valid while the UCharsetMatch
* is valid.
*
* The name returned is suitable for use with the ICU conversion APIs.
*
* @param ucsm The charset match object.
* @param status Any error conditions are reported back in this variable.
* @return The name of the matching charset.
*
* @stable ICU 3.6
*/
U_STABLE const char * U_EXPORT2
ucsdet_getName(const UCharsetMatch *ucsm, UErrorCode *status);
/**
* Get a confidence number for the quality of the match of the byte
* data with the charset. Confidence numbers range from zero to 100,
* with 100 representing complete confidence and zero representing
* no confidence.
*
* The confidence values are somewhat arbitrary. They define an
* an ordering within the results for any single detection operation
* but are not generally comparable between the results for different input.
*
* A confidence value of ten does have a general meaning - it is used
* for charsets that can represent the input data, but for which there
* is no other indication that suggests that the charset is the correct one.
* Pure 7 bit ASCII data, for example, is compatible with a
* great many charsets, most of which will appear as possible matches
* with a confidence of 10.
*
* @param ucsm The charset match object.
* @param status Any error conditions are reported back in this variable.
* @return A confidence number for the charset match.
*
* @stable ICU 3.6
*/
U_STABLE int32_t U_EXPORT2
ucsdet_getConfidence(const UCharsetMatch *ucsm, UErrorCode *status);
/**
* Get the RFC 3066 code for the language of the input data.
*
* The Charset Detection service is intended primarily for detecting
* charsets, not language. For some, but not all, charsets, a language is
* identified as a byproduct of the detection process, and that is what
* is returned by this function.
*
* CAUTION:
* 1. Language information is not available for input data encoded in
* all charsets. In particular, no language is identified
* for UTF-8 input data.
*
* 2. Closely related languages may sometimes be confused.
*
* If more accurate language detection is required, a linguistic
* analysis package should be used.
*
* The storage for the returned name string is owned by the
* UCharsetMatch, and will remain valid while the UCharsetMatch
* is valid.
*
* @param ucsm The charset match object.
* @param status Any error conditions are reported back in this variable.
* @return The RFC 3066 code for the language of the input data, or
* an empty string if the language could not be determined.
*
* @stable ICU 3.6
*/
U_STABLE const char * U_EXPORT2
ucsdet_getLanguage(const UCharsetMatch *ucsm, UErrorCode *status);
/**
* Get the entire input text as a UChar string, placing it into
* a caller-supplied buffer. A terminating
* NUL character will be appended to the buffer if space is available.
*
* The number of UChars in the output string, not including the terminating
* NUL, is returned.
*
* If the supplied buffer is smaller than required to hold the output,
* the contents of the buffer are undefined. The full output string length
* (in UChars) is returned as always, and can be used to allocate a buffer
* of the correct size.
*
*
* @param ucsm The charset match object.
* @param buf A UChar buffer to be filled with the converted text data.
* @param cap The capacity of the buffer in UChars.
* @param status Any error conditions are reported back in this variable.
* @return The number of UChars in the output string.
*
* @stable ICU 3.6
*/
U_STABLE int32_t U_EXPORT2
ucsdet_getUChars(const UCharsetMatch *ucsm,
UChar *buf, int32_t cap, UErrorCode *status);
/**
* Get an iterator over the set of all detectable charsets -
* over the charsets that are known to the charset detection
* service.
*
* The returned UEnumeration provides access to the names of
* the charsets.
*
* <p>
* The state of the Charset detector that is passed in does not
* affect the result of this function, but requiring a valid, open
* charset detector as a parameter insures that the charset detection
* service has been safely initialized and that the required detection
* data is available.
*
* <p>
* <b>Note:</b> Multiple different charset encodings in a same family may use
* a single shared name in this implementation. For example, this method returns
* an array including "ISO-8859-1" (ISO Latin 1), but not including "windows-1252"
* (Windows Latin 1). However, actual detection result could be "windows-1252"
* when the input data matches Latin 1 code points with any points only available
* in "windows-1252".
*
* @param ucsd a Charset detector.
* @param status Any error conditions are reported back in this variable.
* @return an iterator providing access to the detectable charset names.
* @stable ICU 3.6
*/
U_STABLE UEnumeration * U_EXPORT2
ucsdet_getAllDetectableCharsets(const UCharsetDetector *ucsd, UErrorCode *status);
/**
* Test whether input filtering is enabled for this charset detector.
* Input filtering removes text that appears to be HTML or xml
* markup from the input before applying the code page detection
* heuristics.
*
* @param ucsd The charset detector to check.
* @return TRUE if filtering is enabled.
* @stable ICU 3.6
*/
U_STABLE UBool U_EXPORT2
ucsdet_isInputFilterEnabled(const UCharsetDetector *ucsd);
/**
* Enable filtering of input text. If filtering is enabled,
* text within angle brackets ("<" and ">") will be removed
* before detection, which will remove most HTML or xml markup.
*
* @param ucsd the charset detector to be modified.
* @param filter <code>true</code> to enable input text filtering.
* @return The previous setting.
*
* @stable ICU 3.6
*/
U_STABLE UBool U_EXPORT2
ucsdet_enableInputFilter(UCharsetDetector *ucsd, UBool filter);
#ifndef U_HIDE_INTERNAL_API
/**
* Get an iterator over the set of detectable charsets -
* over the charsets that are enabled by the specified charset detector.
*
* The returned UEnumeration provides access to the names of
* the charsets.
*
* @param ucsd a Charset detector.
* @param status Any error conditions are reported back in this variable.
* @return an iterator providing access to the detectable charset names by
* the specified charset detector.
* @internal
*/
U_INTERNAL UEnumeration * U_EXPORT2
ucsdet_getDetectableCharsets(const UCharsetDetector *ucsd, UErrorCode *status);
/**
* Enable or disable individual charset encoding.
* A name of charset encoding must be included in the names returned by
* {@link #getAllDetectableCharsets()}.
*
* @param ucsd a Charset detector.
* @param encoding encoding the name of charset encoding.
* @param enabled <code>TRUE</code> to enable, or <code>FALSE</code> to disable the
* charset encoding.
* @param status receives the return status. When the name of charset encoding
* is not supported, U_ILLEGAL_ARGUMENT_ERROR is set.
* @internal
*/
U_INTERNAL void U_EXPORT2
ucsdet_setDetectableCharset(UCharsetDetector *ucsd, const char *encoding, UBool enabled, UErrorCode *status);
#endif /* U_HIDE_INTERNAL_API */
#endif
#endif /* __UCSDET_H */