1//===- llvm/Support/Unicode.h - Unicode character properties -*- C++ -*-=====//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file defines functions that allow querying certain properties of Unicode
10// characters.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_SUPPORT_UNICODE_H
15#define LLVM_SUPPORT_UNICODE_H
16
17#include "llvm/ADT/SmallString.h"
18#include "llvm/Support/Compiler.h"
19#include <optional>
20#include <string>
21
22namespace llvm {
23class StringRef;
24
25namespace sys {
26namespace unicode {
27
28enum ColumnWidthErrors {
29 ErrorInvalidUTF8 = -2,
30 ErrorNonPrintableCharacter = -1
31};
32
33/// Determines if a character is likely to be displayed correctly on the
34/// terminal. Exact implementation would have to depend on the specific
35/// terminal, so we define the semantic that should be suitable for generic case
36/// of a terminal capable to output Unicode characters.
37///
38/// Printable codepoints are those in the categories L, M, N, P, S and Zs
39/// \return true if the character is considered printable.
40LLVM_ABI bool isPrintable(int UCS);
41
42// Formatting codepoints are codepoints in the Cf category.
43LLVM_ABI bool isFormatting(int UCS);
44
45/// Gets the number of positions the UTF8-encoded \p Text is likely to occupy
46/// when output on a terminal ("character width"). This depends on the
47/// implementation of the terminal, and there's no standard definition of
48/// character width.
49///
50/// The implementation defines it in a way that is expected to be compatible
51/// with a generic Unicode-capable terminal.
52///
53/// \return Character width:
54/// * ErrorNonPrintableCharacter (-1) if \p Text contains non-printable
55/// characters (as identified by isPrintable);
56/// * 0 for each non-spacing and enclosing combining mark;
57/// * 2 for each CJK character excluding halfwidth forms;
58/// * 1 for each of the remaining characters.
59LLVM_ABI int columnWidthUTF8(StringRef Text);
60
61/// Fold input unicode character according the Simple unicode case folding
62/// rules.
63LLVM_ABI int foldCharSimple(int C);
64
65/// Maps the name or the alias of a Unicode character to its associated
66/// codepoints.
67/// The names and aliases are derived from UnicodeData.txt and NameAliases.txt
68/// For compatibility with the semantics of named character escape sequences in
69/// C++, this mapping does an exact match sensitive to casing and spacing.
70/// \return The codepoint of the corresponding character, if any.
71LLVM_ABI std::optional<char32_t> nameToCodepointStrict(StringRef Name);
72
73struct LooseMatchingResult {
74 char32_t CodePoint;
75 SmallString<64> Name;
76};
77
78LLVM_ABI std::optional<LooseMatchingResult>
79nameToCodepointLooseMatching(StringRef Name);
80
81struct MatchForCodepointName {
82 std::string Name;
83 uint32_t Distance = 0;
84 char32_t Value = 0;
85};
86
87LLVM_ABI SmallVector<MatchForCodepointName>
88nearestMatchesForCodepointName(StringRef Pattern, std::size_t MaxMatchesCount);
89
90} // namespace unicode
91} // namespace sys
92} // namespace llvm
93
94#endif
95