Predicate Format String Syntax

相关链接： https://nshipster.cn/nspredicate/
官方文档链接：https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Predicates/Articles/pSyntax.html#//apple_ref/doc/uid/TP40001795-SW1
This article describes the syntax of the predicate string and some aspects of the predicate parser.

• 本文描述了谓词字符串的语法和谓词解析器的一些方面。

The parser string is different from a string expression passed to the regex engine. This article describes the parser text, not the syntax for the regex engine.

• 解析器字符串与传递给正则表达式引擎的字符串表达式不同。 本文介绍了解析器文本，而不是正则表达式引擎的语法。

Parser Basics

The predicate string parser is whitespace insensitive, case insensitive with respect to keywords, and supports nested parenthetical expressions. The parser does not perform semantic type checking.

• 谓词字符串解析器对空格不敏感，对关键字不区分大小写，并支持嵌套的括号表达式。 解析器不执行语义类型检查。

Variables are denoted with a dollar-sign ($) character (for example, $VARIABLE_NAME). The question mark (?) character is not a valid parser token.

• 变量用美元符号（$）字符表示（例如，$ VARIABLE_NAME）。 问号（？）字符不是有效的解析器标记。

The format string supports printf-style format specifiers such as %x (see Formatting String Objects). Two important format specifiers are %@ and %K.
格式字符串支持printf样式的格式说明符，例如％x（请参阅格式化字符串对象）。 两个重要的格式说明符是％@和％K。

• %@ is a var arg substitution for an object value—often a string, number, or date.
  ％@是对象值的var arg替换 - 通常是字符串，数字或日期。

• %K is a var arg substitution for a key path.
  ％K是密钥路径的var arg替换。

When string variables are substituted into a string using the %@ format specifier, they are surrounded by quotation marks. If you want to specify a dynamic property name, use %K in the format string, as shown in the following example.

• 使用％@格式说明符将字符串变量替换为字符串时，它们被引号括起来。 如果要指定动态属性名称，请在格式字符串中使用％K，如以下示例所示。

NSString *attributeName  = @"firstName";
NSString *attributeValue = @"Adam";
NSPredicate *predicate   = [NSPredicate predicateWithFormat:@"%K like %@",
        attributeName, attributeValue];

The predicate format string in this case evaluates to firstName like "Adam".

• 在这种情况下，谓词格式字符串的计算结果为firstName，如“Adam”。

Single or double quoting variables (or substitution variable strings) cause %@, %K, or $variable to be interpreted as a literal in the format string and so prevent any substitution. In the following example, the predicate format string evaluates to firstName like "%@" (note the single quotes around %@).

• 单引号或双引号变量（或替换变量字符串）会导致％@，％K或$变量被解释为格式字符串中的文字，因此可以防止任何替换。 在以下示例中，谓词格式字符串的计算结果为firstName，如“％@”（请注意％@周围的单引号）。

NSString *attributeName = @"firstName";
NSString *attributeValue = @"Adam";
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"%K like '%@'",
        attributeName, attributeValue];

Important: Use a %@ format specifier only to represent an expression. Do not use it to represent an entire predicate.

• 要点：仅使用％@格式说明符表示表达式。 不要用它来表示整个谓词。

If you attempt to use a format specifier to represent an entire predicate, the system raises an exception.

• 如果尝试使用格式说明符表示整个谓词，则系统会引发异常。

Basic Comparisons

=, ==, The left-hand expression is equal to the right-hand expression.

• 左表达式等于右表达式。

>=, =>, The left-hand expression is greater than or equal to the right-hand expression.

• 左表达式大于或等于右表达式。

<=, =<, The left-hand expression is less than or equal to the right-hand expression.

• 左表达式小于或等于右表达式。

>, The left-hand expression is greater than the right-hand expression.

• 左表达式大于右表达式。

<, The left-hand expression is less than the right-hand expression.

• 左表达式小于右表达式。

!=, <>, The left-hand expression is not equal to the right-hand expression.
左表达式不等于右表达式。

BETWEEN
The left-hand expression is between, or equal to either of, the values specified in the right-hand side.
左表达式在右指定的值之间或等于任何一个值。

The right-hand side is a two value array (an array is required to specify order) giving upper and lower bounds. For example, 1 BETWEEN { 0 , 33 }, or $INPUT BETWEEN {$LOWER, $UPPER }.
In Objective-C, you could create a BETWEEN predicate as shown in the following example:

• 右侧是一个两值数组（需要一个数组来指定顺序），给出上限和下限。 例如，1 BETWEEN {0,33}或$ INPUT BETWEEN {$LOWER，$UPPER}。
  在Objective-C中，您可以创建BETWEEN谓词，如以下示例所示：

NSPredicate *betweenPredicate =
    [NSPredicate predicateWithFormat: @"attributeName BETWEEN %@", @[@1, @10]];

This creates a predicate that matches ( ( 1 <= attributeValue ) && ( attributeValue <= 10 ) ), as illustrated in the following example:

• 这将创建一个匹配（（1 <= attributeValue）&&（attributeValue <= 10））的谓词，如以下示例所示：

NSPredicate *betweenPredicate =
    [NSPredicate predicateWithFormat: @"attributeName BETWEEN %@", @[@1, @10]];
 
NSDictionary *dictionary = @{ @"attributeName" : @5 };
 
BOOL between = [betweenPredicate evaluateWithObject:dictionary];
if (between) {
    NSLog(@"between");
}

Boolean Value Predicates

TRUEPREDICATE
A predicate that always evaluates to TRUE.

• 始终计算为TRUE的谓词。
  FALSEPREDICATE

A predicate that always evaluates to FALSE.

• 一个总是计算为FALSE的谓词。

Basic Compound Predicates

AND, &&
Logical AND.

OR, ||
Logical OR.

NOT, !
Logical NOT.

String Comparisons

String comparisons are, by default, case and diacritic sensitive. You can modify an operator using the key characters c and d within square braces to specify case and diacritic insensitivity respectively, for example firstName BEGINSWITH[cd] $FIRST_NAME.

• 默认情况下，字符串比较是大小写和变音符号敏感的。 您可以使用方括号内的键字符c和d修改运算符，以分别指定大小写和变音符号不敏感，例如firstName BEGINSWITH [cd] $ FIRST_NAME。

BEGINSWITH
The left-hand expression begins with the right-hand expression.

• 左表达式以右表达式开头。

CONTAINS
The left-hand expression contains the right-hand expression.

• 左侧表达式包含右侧表达式。

ENDSWITH
The left-hand expression ends with the right-hand expression.
-左侧表达以右侧表达结束。

LIKE
The left hand expression equals the right-hand expression: ? and * are allowed as wildcard characters, where ? matches 1 character and * matches 0 or more characters.

• 左侧表达式等于右侧表达式：?和*被允许作为通配符，条件?允许匹配1个字符，*匹配0个或更多字符。

MATCHES
The left hand expression equals the right hand expression using a regex-style comparison according to ICU v3 (for more details see the ICU User Guide for Regular Expressions).

• 根据ICU v3，左侧表达式使用正则表达式比较等于右侧表达（有关详细信息，请参阅ICU用户指南中的正则表达式）。

UTI-CONFORMS-TO
The left hand argument to this operator is an expression that evaluates to a universal type identifier (UTI) you want to match. The right hand argument is an expression that evaluates to a UTI. The comparison evaluates to TRUE if the UTI returned by the left hand expression conforms to the UTI returned by the right hand expression. For information on which types conform to a given type, see System-Declared Uniform Type Identifiers in Uniform Type Identifiers

• 此运算符的左侧参数是一个表达式，其计算结果为您要匹配的通用类型标识符（UTI）。 右手参数是一个评估为UTI的表达式。 如果左手表达式返回的UTI符合右手表达式返回的UTI，则比较结果为TRUE。 有关哪些类型符合给定类型的信息，请参阅统一类型标识符中的系统声明的统一类型标识符

The clause A UTI-CONFORMS-TO B provides the same result as employing the UTTypeConformsTo method as follows:

• A UTI-CONFORMS-TO B子句提供与使用UTTypeConformsTo方法相同的结果，如下所示：

UTTypeConformsTo (A, B)

When evaluating attachments in an app extension item (of type NSExtensionItem), you could use a statement similar to the following:

• 在评估应用程序扩展项（NSExtensionItem类型）中的附件时，您可以使用类似于以下内容的语句：

SUBQUERY (
    extensionItems,
    $extensionItem,
    SUBQUERY (
        $extensionItem.attachments,
        $attachment,
        ANY $attachment.registeredTypeIdentifiers UTI-CONFORMS-TO "com.adobe.pdf"
    ).@count == $extensionItem.attachments.@count
).@count == 1

UTI-EQUALS
The left hand argument to this operator is an expression that evaluates to a universal type identifier (UTI) you want to match. The right hand argument is an expression that evaluates to a UTI. The comparison evaluates to TRUE if the UTI returned by the left hand expression equals the UTI returned by the right hand expression.

• 此运算符的左侧参数是一个表达式，其计算结果为您要匹配的通用类型标识符（UTI）。 右侧参数是一个评估为UTI的表达式。 如果左侧表达式返回的UTI等于右侧表达式返回的UTI，则比较结果为TRUE。

The clause A UTI-EQUALS B provides the same result as employing the UTTypeEqual method as follows:

• A UTI-EQUALS B子句提供与使用UTTypeEqual方法相同的结果，如下所示：

UTTypeEqual (A, B)

See the code example in the UTI-CONFORMS-TO entry, which applies as well to the UTI-EQUALS operator by replacing the operator.

• 请参阅UTI-CONFORMS-TO条目中的代码示例，该条目通过替换运算符也适用于UTI-EQUALS运算符。

Aggregate Operations 聚合操作

ANY, SOME
Specifies any of the elements in the following expression. For example ANY children.age < 18.

• 指定以下表达式中的任何元素。 例如，任何children.age <18。

ALL
Specifies all of the elements in the following expression. For example ALL children.age < 18.

• 指定以下表达式中的所有元素。 例如，所有children.age <18。

NONE
Specifies none of the elements in the following expression. For example, NONE children.age < 18. This is logically equivalent to NOT (ANY ...).

• 不指定以下表达式中的元素。 例如，NONE children.age <18。这在逻辑上等同于NOT（ANY ...）。

IN
Equivalent to an SQL IN operation, the left-hand side must appear in the collection specified by the right-hand side.

• 相当于SQL IN操作，左侧必须出现在右侧指定的集合中。

For example, name IN { 'Ben', 'Melissa', 'Nick' }. The collection may be an array, a set, or a dictionary—in the case of a dictionary, its values are used.

• 例如，名字IN {'Ben'，'Melissa'，'Nick'}。 集合可以是数组，集合或字典 - 在字典的情况下，使用其值。

In Objective-C, you could create a IN predicate as shown in the following example:

• 在Objective-C中，您可以创建一个IN谓词，如以下示例所示：

NSPredicate *inPredicate =
            [NSPredicate predicateWithFormat: @"attribute IN %@", aCollection];

where aCollection may be an instance of NSArray, NSSet, NSDictionary, or of any of the corresponding mutable classes.

• 其中aCollection可以是NSArray，NSSet，NSDictionary或任何相应的可变类的实例。

array[index]
Specifies the element at the specified index in the array array.

• 指定数组数组中指定索引处的元素。

array[FIRST]
Specifies the first element in the array array.

• 指定数组数组中的第一个元素。

array[LAST]
Specifies the last element in the array array.
指定数组数组中的最后一个元素。

array[SIZE]
Specifies the size of the array array.

• 指定数组数组的大小。
  Identifiers

C style identifier
Any C style identifier that is not a reserved word.

• 任何不是保留字的C样式标识符。

symbol

Used to escape a reserved word into a user identifier.

• 用于将保留字转义为用户标识符。

[]{octaldigit}{3}
Used to escape an octal number ( \ followed by 3 octal digits).

• 用于转义八进制数字（\后跟3个八进制数字）。

[][xX]{hexdigit}{2}
Used to escape a hex number ( \x or \X followed by 2 hex digits).

• 用于转义十六进制数字（\ x或\ X后跟2个十六进制数字）。

[][uU]{hexdigit}{4}
Used to escape a Unicode number ( \u or \U followed by 4 hex digits).

• 用于转义Unicode编号（\ u或\ U后跟4个十六进制数字）。
  Literals

Single and double quotes produce the same result, but they do not terminate each other. For example, "abc" and 'abc' are identical, whereas "a'b'c" is equivalent to a space-separated concatenation of a, 'b', c.

• 单引号和双引号产生相同的结果，但它们不会相互终止。 例如，“abc”和“abc”是相同的，而“a'b'c”相当于a，'b'，c的空格分隔的连接。

FALSE, NO
Logical false.

TRUE, YES
Logical true.

NULL, NIL
A null value.

SELF
Represents the object being evaluated.

"text"
A character string.

'text'
A character string.

Comma-separated literal array
For example, { 'comma', 'separated', 'literal', 'array' }.

Standard integer and fixed-point notations
For example, 1, 27, 2.71828, 19.75.

Floating-point notation with exponentiation
For example, 9.2e-5.

0x
Prefix used to denote a hexadecimal digit sequence.

• 前缀用于表示十六进制数字序列。

0o
Prefix used to denote an octal digit sequence.
-前缀用于表示八进制数字序列。

0b
Prefix used to denote a binary digit sequence.

• 前缀用于表示二进制数字序列。

Reserved Words

The following words are reserved:

AND, OR, IN, NOT, ALL, ANY, SOME, NONE, LIKE, CASEINSENSITIVE, CI, MATCHES, CONTAINS, BEGINSWITH, ENDSWITH, BETWEEN, NULL, NIL, SELF, TRUE, YES, FALSE, NO, FIRST, LAST, SIZE, ANYKEY, SUBQUERY, FETCH, CAST, TRUEPREDICATE, FALSEPREDICATE, UTI-CONFORMS-TO, UTI-EQUALS,