field: Document return value of fe_sqrt() #1347

1. 
   real-or-random commented at 9:50 am on June 15, 2023: contributor
2. real-or-random added the label documentation on Jun 15, 2023
3. 
   real-or-random commented at 9:51 am on June 15, 2023: contributor

   @stratospher Interested in reviewing this small PR?
4. real-or-random cross-referenced this on Jun 15, 2023 from issue ElligatorSwift + integrated x-only DH by sipa
5. in src/field.h:271 in c66c30cd57 outdated

   266@@ -267,8 +267,10 @@ static void secp256k1_fe_sqr(secp256k1_fe *r, const secp256k1_fe *a);
   267 /** Compute a square root of a field element.
   268  *
   269  * On input, a must be a valid field element with magnitude<=8; r need not be initialized.
   270- * Performs {r = sqrt(a)} or {r = sqrt(-a)}, whichever exists. The resulting value
   271- * represented by r will be a square itself. Variables r and a must not point to the same object.
   272+ * Performs {r = sqrt(a)} and returns 1 if sqrt(a) exists.
   273+ * Performs {r = sqrt(-a) and returns 0 otherwise; then sqrt(-a) exists.
   

   ---

   ---

   

   stratospher commented at 3:21 pm on June 15, 2023:

   c66c30c: nit

   0 * Performs {r = sqrt(-a)} and returns 0 otherwise; then sqrt(-a) exists.
   

6. 
   stratospher commented at 3:21 pm on June 15, 2023: contributor

   ACK c66c30c.
7. real-or-random force-pushed on Jun 15, 2023
8. 
   stratospher commented at 3:26 pm on June 15, 2023: contributor

   ACK cc1ad2f.
9. in src/field.h:271 in cc1ad2f97e outdated

   266@@ -267,8 +267,10 @@ static void secp256k1_fe_sqr(secp256k1_fe *r, const secp256k1_fe *a);
   267 /** Compute a square root of a field element.
   268  *
   269  * On input, a must be a valid field element with magnitude<=8; r need not be initialized.
   270- * Performs {r = sqrt(a)} or {r = sqrt(-a)}, whichever exists. The resulting value
   271- * represented by r will be a square itself. Variables r and a must not point to the same object.
   272+ * Performs {r = sqrt(a)} and returns 1 if sqrt(a) exists.
   273+ * Performs {r = sqrt(-a)} and returns 0 otherwise; then sqrt(-a) exists.
   

   ---

   ---

   

   jonasnick commented at 3:22 pm on June 16, 2023:

   nit: maybe case distinction like this is clearer?

   0 * If sqrt(a) exists, performs {r = sqrt(a)} and returns 1.
   1 * Otherwise, sqrt(-a) exists. The function performs {r = sqrt(-a)} and returns 0.
   

   ---

   

   real-or-random commented at 10:19 pm on June 20, 2023:

   Done.
10. field: Document return value of fe_sqrt()

    Co-authored-by: Jonas Nick <jonasd.nick@gmail.com>

    5779137457
11. real-or-random force-pushed on Jun 20, 2023
12. 
    sipa commented at 11:45 pm on June 20, 2023: contributor

    ACK 57791374579595bbc5d8d2e55f7fa0bc40d861a4
13. theStack approved
14. 
    theStack commented at 3:30 pm on June 21, 2023: contributor

    ACK 57791374579595bbc5d8d2e55f7fa0bc40d861a4
15. real-or-random merged this on Jun 21, 2023
16. real-or-random closed this on Jun 21, 2023

    ---

17. vmta referenced this in commit 8f03457eed on Jul 1, 2023
18. fanquake referenced this in commit 56c05c5ec4 on Jul 17, 2023
19. fanquake referenced this in commit ff061fde18 on Jul 18, 2023
20. hebasto referenced this in commit 270d2b37b8 on Jul 21, 2023
21. jonasnick cross-referenced this on Jul 26, 2023 from issue Upstream PRs 1314, 1317, 1318, 1316, 1327, 1310, 1328, 1333, 1330, 1334, 1337, 1341, 1339, 1350, 1349, 1338, 1129, 1347, 1336, 1295, 1354, 1355, 1356 by jonasnick

Contributors
real-or-random stratospher jonasnick sipa theStack

Labels
documentation